Known Date

<quiet-known-date>

stable

since 5.2

form control

This component is a form-associated custom element. It will submit its value when given a name and placed inside a <form>.

Collects a memorable date through separate day, month, and year fields and submits them as a single value. Use a known date for birthdays, anniversaries, and other dates the user can enter without a calendar.

Each field is input separately, but the date is stored as a single ISO 8601 string in YYYY-MM-DD format so you receive one clean value on the server. The same string is exposed through the value property, so you can get or set the whole date in one go.

The three-field pattern isn't arbitrary. The GOV.UK Design System recommends separate day, month, and year fields for dates users already know or can look up, as testing found them faster and less error-prone than dropdowns or calendars.

<quiet-known-date name="dob" label="Date of birth"></quiet-known-date>

For a calendar primitive, see date picker. For a date input with calendar, see date input.

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the known date. If you want to provide HTML, use the label and description slots instead.

Enter the date exactly as it appears on your ID.

<quiet-known-date name="dob" label="Date of birth">
  <span slot="description">
    Enter the date exactly as it appears <a href="https://example.com/">on your ID</a>.
  </span>
</quiet-known-date>

Providing an initial value Jump to heading

Use the value attribute to provide an initial value for the known date. The value must be an ISO 8601 date string in YYYY-MM-DD format.

When the date is incomplete or isn't a real calendar date, the value will be an empty string. This way, your form never receives a half-populated or malformed date. To ensure users complete the field before submitting, see the validation section below.

<quiet-known-date name="dob" label="Date of birth" value="1990-07-12"></quiet-known-date>

Prefilling individual fields Jump to heading

Sometimes you'll want to prefill part of a date and let the user complete the rest. Use the day, month, and year attributes to set each field independently. The example below fills in the month and year, leaving the day for the user to enter.

The month attribute accepts a number from 1 to 12. Until all three fields form a complete, valid date, value will be an empty string and nothing will be submitted with the form. If you provide both value and individual fields, value takes precedence.

<quiet-known-date name="dob" label="Date of birth" month="5" year="1990"></quiet-known-date>

Setting a minimum and maximum date Jump to heading

Use the min and max attributes to restrict the range of acceptable dates. Both accept an ISO 8601 date string. The known date will be invalid when the selected date falls outside the range.

<form action="about:blank" method="get" target="_blank">
  <quiet-known-date
    name="appointment"
    label="Appointment date"
    description="Choose a date in 2026."
    min="2026-01-01"
    max="2026-12-31"
  ></quiet-known-date>
  <br>
  <quiet-button type="submit">Submit</quiet-button>
</form>

Localized field order Jump to heading

The known date shows its fields in the order that's natural for the user's locale. This resolves to day/month/year for much of the world, month/day/year in the United States, and year/month/day in many parts of Asia. Set the lang attribute to see how the order adapts.

No matter how the fields are arranged, the submitted value stays in YYYY-MM-DD format. The field order and localized month names come from the browser's Intl API automatically, so they work for any lang with no setup.

<quiet-known-date lang="en-GB" label="British English (day, month, year)" value="2026-04-15"></quiet-known-date>
<br>
<quiet-known-date lang="en-US" label="American English (month, day, year)" value="2026-04-15"></quiet-known-date>
<br>
<quiet-known-date lang="ja" label="Japanese (year, month, day)" value="2026-04-15"></quiet-known-date>

<script type="module">
  // Field order and month names come from the browser's Intl API automatically, but the Day, Month, and
  // Year labels are translated terms — import the matching translation to localize them.
  import '/dist/translations/ja.js';
</script>

Typing to select the month Jump to heading

When focused, the month field inherits the browser's native typeahead for names, so typing ju will move the selection to June. The component also accepts numeric input, e.g typing 8 or 08 will move the selection to August.

This behavior lets users enter the target month as efficiently as possible.

Focus and blur events Jump to heading

The known date is a single form control, but it contains three internal fields. Each field is its own tab stop, so as the user tabs through the component you'll see the quiet-focus and quiet-blur events dispatch up to three times (once per field) even though there's only one host element.

To tell the fields apart, inspect the event's detail.field property, which is set to day, month, or year.

<quiet-known-date id="known-date__events" name="dob" label="Date of birth"></quiet-known-date>

<script type="module">
  const knownDate = document.getElementById('known-date__events');

  knownDate.addEventListener('quiet-focus', event => {
    console.log(`Focused the ${event.detail.field} field`);
  });

  knownDate.addEventListener('quiet-blur', event => {
    console.log(`Blurred the ${event.detail.field} field`);
  });
</script>

If you only care about the component as a whole, listen for quiet-change instead. This event is dispatched just once, and only when the submitted value actually changes.

Changing the appearance Jump to heading

Set the appearance attribute to normal, filled, or unstyled to change the known date's appearance.

<quiet-known-date appearance="normal" label="Normal"></quiet-known-date>
<br>
<quiet-known-date appearance="filled" label="Filled"></quiet-known-date>
<br>
<quiet-known-date appearance="unstyled" label="Unstyled"></quiet-known-date>

Pill-shaped known dates Jump to heading

Known dates can be rendered with pill-shaped edges by adding the pill attribute.

<quiet-known-date pill label="Pill-shaped"></quiet-known-date>

Changing the size Jump to heading

Use the size attribute to change the known date's size. A container query is used to stack the form controls when screen space doesn't permit keeping them on the same line.

<div id="known-date__size">
  <quiet-known-date size="xs" label="Extra small"></quiet-known-date>
  <br>
  <quiet-known-date size="sm" label="Small"></quiet-known-date>
  <br>
  <quiet-known-date size="md" label="Medium"></quiet-known-date>
  <br>
  <quiet-known-date size="lg" label="Large"></quiet-known-date>
  <br>
  <quiet-known-date size="xl" label="Extra large"></quiet-known-date>
</div>

<style>
  #known-date__size quiet-known-date {
    max-width: 26em;
  }
</style>

Disabling Jump to heading

Use the disabled attribute to disable the known date.

<quiet-known-date label="Disabled" value="1990-07-12" disabled></quiet-known-date>

Validation Jump to heading

The required attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until all three fields are filled in with a valid date.

The known date is also invalid when the entered date is incomplete, isn't a real calendar date (such as February 30), or falls outside the min/max range.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-known-date name="dob" label="Date of birth" required></quiet-known-date>
  <br>
  <quiet-button type="submit">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the setCustomValidity() method to make the known date invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, set it to an empty string.

<form action="about:blank" method="get" target="_blank" id="known-date__custom-validation">
  <quiet-known-date
    name="dob"
    label="Date of birth"
    description="This field will be invalid until custom validation is removed"
  ></quiet-known-date>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

<script type="module">
  import { allDefined } from '/dist/quiet.js';

  await allDefined();

  const form = document.getElementById('known-date__custom-validation');
  const knownDate = form.querySelector('quiet-known-date');

  knownDate.setCustomValidity('Not so fast, bubba!');
</script>

Styling validation Jump to heading

You can style valid and invalid known dates using the :valid and :invalid pseudo classes.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="known-date__validation-pseudo">
  <quiet-known-date name="dob" label="Date of birth" description="This field is required" required></quiet-known-date>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .known-date__validation-pseudo {
    quiet-known-date:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-known-date:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="known-date__validation-custom">
  <quiet-known-date name="dob" label="Date of birth" description="This field is required" required></quiet-known-date>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .known-date__validation-custom {
    quiet-known-date:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-known-date:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

Self-hosted

To manually import <quiet-known-date> from the CDN, use the following code.

import 'https://cdn.quietui.org/v5.2.0/components/known-date/known-date.js';

To manually import <quiet-known-date> from a self-hosted distribution, use the following code. Remember to replace /path/to/quiet with the appropriate local path.

import '/path/to/quiet/components/known-date/known-date.js';

Slots Jump to heading

Known Date supports the following slots. Learn more about using slots

Name	Description
`label`	The known date's label. For plain-text labels, you can use the `label` attribute instead.
`description`	The known date's description. For plain-text descriptions, you can use the `description` attribute instead.

Properties Jump to heading

Known Date has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property	Description	Type	Default
`label`	The known date's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The known date's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`name`	The name of the known date. This will be submitted with the form as a name/value pair.	`string`
`value`	The known date's value as an ISO 8601 date string in `YYYY-MM-DD` format. When the date is incomplete or invalid, the value will be an empty string. Setting this populates the day, month, and year fields; setting any of those recomposes this value.	`string`	`''`
`day`	The day field's value, as a string. Useful for prefilling a single field — for example, setting `month` and `year` while leaving `day` blank for the user. `value` stays empty until all three fields form a complete date.	`string`	`''`
`month`	The month field's value, as a `1`–`12` string. Useful for prefilling a single field. `value` stays empty until all three fields form a complete date.	`string`	`''`
`year`	The year field's value, as a string. Useful for prefilling a single field. `value` stays empty until all three fields form a complete date.	`string`	`''`
`min`	The earliest date the user can select, as a `YYYY-MM-DD` string.	`string`
`max`	The latest date the user can select, as a `YYYY-MM-DD` string.	`string`
`disabled`	Disables the known date.	`boolean`	`false`
`readonly`	Makes the known date a read-only field.	`boolean`	`false`
`appearance`	The type of known date to render.	`'normal' \| 'filled' \| 'unstyled'`	`'normal'`
`size`	The known date's size.	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
`pill`	Draws the known date in a pill shape.	`boolean`	`false`
`required`	Makes the known date required. Form submission will not be allowed when this is set and the known date is blank.	`boolean`	`false`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an ID of a form in the same document or shadow root.	`string`

Methods Jump to heading

Known Date supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the known date. Focus is placed on the first field in the current locale's order.
`blur()`	Removes focus from the known date.
`setCustomValidity()`	Sets a custom validation message for the known date. If this message is not an empty string, the known date is considered invalid and the message is shown to the user when reporting validity. Setting an empty string clears the custom validity state.	`message: string`
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.
`setCustomValidity()`	Sets a custom validation message for the form control. If this message is not an empty string, then the form control is considered invalid and the specified message will be displayed to the user when reporting validity. Setting an empty string clears the custom validity state.	`message: string`

Events Jump to heading

Known Date dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-blur`	Emitted when one of the internal fields loses focus. Because the known date contains three fields, this can be emitted up to three times as the user tabs through the component. The event's `detail.field` property identifies which field (`day`, `month`, or `year`) lost focus. This event does not bubble.
`quiet-change`	Emitted when the user commits a change that alters the known date's value. Unlike the internal fields, this is only emitted when the submitted value actually changes.
`quiet-focus`	Emitted when one of the internal fields receives focus. Because the known date contains three fields, this can be emitted up to three times as the user tabs through the component. The event's `detail.field` property identifies which field (`day`, `month`, or `year`) received focus. This event does not bubble.
`quiet-input`	Emitted when any of the internal fields receives input.

CSS parts Jump to heading

Known Date exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The element that contains the known date's label.	`::part(label)`
`description`	The element that contains the known date's description.	`::part(description)`
`date-fields`	The container that wraps the three internal fields.	`::part(date-fields)`
`day-label`	The label for the day field.	`::part(day-label)`
`day`	The day field, an `<input>` element.	`::part(day)`
`month-label`	The label for the month field.	`::part(month-label)`
`month`	The month field, a `<select>` element.	`::part(month)`
`year-label`	The label for the year field.	`::part(year-label)`
`year`	The year field, an `<input>` element.	`::part(year)`
`chevron`	The chevron icon shown in the month field, a `<quiet-icon>` element.	`::part(chevron)`
`chevron__svg`	The chevron icon's `<svg>` part.	`::part(chevron__svg)`

Custom States Jump to heading

Known Date has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the known date is disabled.	`:state(disabled)`
`blank`	Applied when all three of the known date's fields are empty.	`:state(blank)`
`focused`	Applied when any of the known date's fields has focus.	`:state(focused)`
`user-valid`	Applied when the known date is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the known date is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Dependencies Jump to heading

Known Date automatically imports the following elements. Sub-dependencies are also included in this list.

<quiet-icon>

Known Date

Examples Jump to heading #

Labels and descriptions Jump to heading #

Providing an initial value Jump to heading #

Prefilling individual fields Jump to heading #

Setting a minimum and maximum date Jump to heading #

Localized field order Jump to heading #

Typing to select the month Jump to heading #

Focus and blur events Jump to heading #

Changing the appearance Jump to heading #

Pill-shaped known dates Jump to heading #

Changing the size Jump to heading #

Disabling Jump to heading #

Validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #