DatePicker

DatePicker allows a user to select a date or date range from a dropdown calendar.

Structure

DatePicker renders its field through the TextField component as a native HTML <input> with the combobox role and the readonly attribute. Assistive technology announces it as a read-only combobox, because the date is chosen in a Popover rather than typed.

The Popover uses Floating UI, whose useRole hook assigns the dialog role and the field's related ARIA attributes, and whose useDismiss hook closes the Popover with the Escape key or an outside click. The Popover contains a <table> with the grid role, where each day is a native <button>. Depending on the type, the Popover also holds a list of preset buttons or time controls with a Save and Close button.

ARIA

table
Element	Attribute	Description
AM/PM select	`aria-label`	Set to "AM/PM selection", prefixed with "Start time" or "End time" in time ranges.
Calendar	`aria-label`	Names the grid with the visible month and year, such as "March 2026".
Calendar	`role="grid"`	Identifies the calendar as a grid of days navigable with arrow keys.
Calendar weekday row	`aria-hidden="true"`	Hides the abbreviated weekday names from the accessibility tree.
Clear button	`aria-label="Clear field"`	Provides an accessible name for the icon-only clear button rendered when `isClearable` is set.
Day button	`aria-disabled`	Set when the day can't be selected because of the date limits or, while a range is being chosen, the range length limits, keeping the day focusable.
Day button	`aria-label`	Names the day with its date in ISO format, such as "2026-03-12".
Day cell	`aria-selected`	Set to `true` on every day within the current selection, including the range being chosen.
Day cell	`role="gridcell"`	Identifies each day as a cell within the calendar grid.
Field	`aria-controls`	References the Popover's ID while the Popover is open.
Field	`aria-describedby`	References any `ariaDescribedby` IDs, then the description, then the error, including each one that is present.
Field	`aria-expanded`	Set to `true` when the Popover is open, `false` when closed or when the field is disabled.
Field	`aria-haspopup="dialog"`	Indicates the field opens a dialog, including while the field is disabled.
Field	`aria-invalid`	Set when the field is invalid, either through `isInvalid` or by an `error` being present.
Field	`aria-label`	Set from the `ariaLabel` prop to provide an accessible name when no visible label is rendered.
Field	`aria-labelledby`	References the visible label element's ID. When an `ariaLabelledby` prop is also provided, both IDs are included.
Field	`role="combobox"`	Identifies the field as a combobox that controls the Popover.
Loading spinner	`aria-label="Loading…"`	Provides an accessible name for the spinner shown when `isLoading` is set.
Month select	`aria-label="Month"`	Provides an accessible name for the month select in the calendar header.
Next month button	`aria-label="Next month"`	Provides an accessible name for the icon-only next month button.
Popover	`role="dialog"`	Identifies the floating container as a dialog.
Preset button	`aria-describedby`	References a visually hidden copy of the preset's tooltip text when a tooltip is set.
Preset button	`aria-disabled`	Set when the preset is disabled, keeping the preset focusable.
Previous month button	`aria-label="Previous month"`	Provides an accessible name for the icon-only previous month button.
Time field	`aria-label`	Set to "Hours", "Minutes", or "Seconds", prefixed with "Start time" or "End time" in time ranges.
Time zone select	`aria-label="Timezone"`	Provides an accessible name for the searchable time zone select.
Year select	`aria-label="Year"`	Provides an accessible name for the year select in the calendar header.

Disabled dates

Disabled days and presets use aria-disabled instead of the native disabled attribute. They remain in the arrow-key and tab order, so keyboard and screen reader users can still navigate through them. Activating a disabled day or preset does nothing. For more information, see Date limits under the Design tab for when to set them.

Focus management

The Popover opens when the field is clicked, receives focus, or is activated with Down Arrow, Enter, or Space. Focus moves into the calendar, landing on the selected date, or on today when nothing is selected. Set shouldAutoFocusCalendar to false to keep focus on the field instead.

Focus is trapped within the Popover while it is open, following the Popover's focus trapping behavior. When the Popover closes, focus returns to the field without reopening it.

Labels

We highly recommend adding visible labels with the label prop. If a visible label is unneeded for the use case, such as a DatePicker in a toolbar, add an ariaLabel or ariaLabelledby so assistive technology will announce the DatePicker to the user. Omitting a label will result in an error.

Never use a placeholder in place of a label. Placeholders are not reliably announced to assistive technology, and they are replaced by the value as soon as a date is chosen.

table
Key	Function
`End`	Moves focus to the last day of the month.
`Enter`/`Space`	Selects the focused day. Date types apply the selection and close the Popover, and range types do so once the end of the range is selected.
`Home`	Moves focus to the first day of the month.
`Page Down`	Moves focus to the same day in the next month.
`Page Up`	Moves focus to the same day in the previous month.
`Shift`+`Page Down`	Moves focus to the same day in the next year.
`Shift`+`Page Up`	Moves focus to the same day in the previous year.
`↓`	Moves focus to the same day in the next week.
`←`	Moves focus to the previous day.
`→`	Moves focus to the next day.
`↑`	Moves focus to the same day in the previous week.

Field

table
Key	Function
`Enter`/`Space`	Opens the Popover.
`↓`	Opens the Popover.

table
Key	Function
`Escape`	Closes the Popover without changing the value and returns focus to the field.
`Shift`+`Tab`	Moves focus to the previous focusable element, wrapping from the first element in the Popover to the last.
`Tab`	Moves focus to the next focusable element, wrapping from the last element in the Popover to the first.

Presets

table
Key	Function
`Enter`/`Space`	Selects the preset's range and closes the Popover. In time ranges, selects the range without closing so the time can be adjusted before saving. A preset with a custom action runs that action instead.

DatePicker

Structure

ARIA

Disabled dates

Focus management

Labels

Time selection

Keyboard

Calendar

Field

Popover

Presets

On this page