Date picker

Put the date picker in a Field to give it a label, helper, and error. Without a Field, set aria-label. Inside a Field, set required and disabled on the Field.

Anatomy

The label, helper, and error come from a Field. The calendar is the same size at every field size.

Sizes

The end padding is smaller so the 24px calendar button sits evenly in the box. The heights match Input and Button.

States

The box doesn't change on hover. On focus, its border takes the focus color and grows thicker inward. While the calendar is open and focus is in it, the box shows no focus.

• readonly: people can focus and copy the date; the calendar button doesn't work.
• disabled: nothing works, and the date is left out of the form.
• Error: set error on the Field. The border turns red and the message shows under the box.

Typing a date

The text is read when people press Enter or leave the field, never while they type. These all work:

• 2026-03-27
• 27 mar 2026, March 27, 2026, or 27 March (this year)
• 27 3 2026, 27/3/2026, or 27.3.2026: day, month, year

Years need four digits. After a date is read, the field shows it as "27 Mar 2026".

If the text isn't a real date, the field keeps it, clears the value, and blocks the form from submitting. Show a message with the Field's error; see Content.

Opening the calendar

• The calendar button, or Down in the field, opens the calendar. Focusing, clicking, or typing in the field never opens it.
• Focus moves to the selected day, or today, or the first day people can pick.
• Picking a day sets the value, closes the calendar, and returns focus to the field. There is no OK button.
• Esc, a click outside, or Tab closes it without changing anything. Esc doesn't close a dialog around it.
• People can click back into the field and type while the calendar stays open.

Memorable dates

For a date people know by heart, use Inputs, not a calendar:

• Use one field each for day, month, and year, under a group label such as "Date of birth" and one hint: "For example, 27 3 2007". Or use one field where space is tight.
• Ask for the month as a number, not a select.
• Don't move focus to the next field automatically.
• Set autocomplete on birth dates: bday-day, bday-month, bday-year, or bday on one field.

When to use

Ask whether people already know the date.

• Use a date picker for a near date where the weekday or distance matters: an appointment, a booking, a deadline.
• Use typed fields for a date people know by heart, such as a birth date or an expiry date. See Memorable dates.
• Use a Date range picker for a period. Don't pair two date pickers.
• Use a Time picker for the time, next to the date picker.
• Use a Calendar when the grid should stay visible on the page.

Content

• Name the date's role in the label: "Departure date", not "Date".
• Put the format in the helper with an example: "For example, 27 3 2026". Never only in the placeholder; it disappears when people start typing.
• Pick the first error that applies, and reuse the label's words:

Don't write "Invalid date" or "Please". More in Errors.

Do / Don't

Related

• Field: the label, helper, and error around a date picker.
• Calendar: the grid inside, its keys, and range mode.
• Date range picker: a start and end date.
• Time picker: the time next to a date.
• Input: the box this field shares, and the base for memorable dates.

API

Attributes

Events

change fires when the date changes: after typing a date that reads, or after picking a day. input fires on every keystroke. Setting value in code fires nothing. Resetting the form restores the first value.

CSS

• ::part(field): the bordered box.
• ::part(input): the native text input.
• ::part(popover): the calendar panel.

Tokens

The box uses the Input tokens, and the grid the Calendar tokens. The date picker adds:

In high contrast, the popover also gets a 1px border/default. Values per theme: Color.

Accessibility

Built in:

• A native text input that announces as a combobox with a calendar popup, open or closed.
• The calendar button says "Choose date", or "Change date, 17 Mar 2026" once there is a value.
• Every open moves focus into the calendar, and every close puts focus somewhere sensible.
• A date that can't be read, a missing required date, or a date out of bounds blocks submission and moves focus to the field.
• The calendar button is 24px, the minimum target size.

Your part:

• Name every date picker: a Field label with the date's role, or aria-label.
• Put the format example in the helper.
• Set min and max to the dates that make sense.
• Write errors on the Field, as Content says.

Keys inside the calendar: Calendar.

Contrast limits

• Field border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. Always show a label.