Skip to content

DatePicker

C-13 · Components · Inputs

All elements · DatePicker on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for DatePicker.

DatePicker

C-13WCAG 2.2 AA · Passed #406
Axis Values
mode date · datetime · range
.qf-calendar__day aria-selected · data-today · data-outside · data-in-range · data-range-start/end · :disabled
Trigger and calendar
September 2026 · range
MoTuWeThFrSaSu

Guidance

When to use

  • Use a date picker for a date the user may want to see in calendar context, such as a due date.
  • Use datetime mode when the time matters, such as a scheduled send; the time field sits in the calendar footer.
  • Use range mode for a start and end date, such as a report period or a filter.
  • Use disabled days to block dates that are not allowed, such as weekends or past dates.

When to consider something else

  • If the date is well known to the user, such as a date of birth, use a text field with a clear format hint. See TextField.
  • If the user picks from a few preset periods (Today, This week), use a select. See Select.
  • If dates are only filters in a large grid, use the date filter inside the data grid. See DataGrid.

Usability

Do
  • Show dates in one unambiguous format, such as "14 Aug 2026".
  • Mark today and offer a Today button.
  • Tell the user why a day is disabled, such as in helper text below the field.
  • Let users type a date as well as pick it; picking from a grid alone is slow for keyboard users.
Don’t
  • Don't use a date picker for dates far in the past or future without fast year navigation.
  • Don't show range state by color alone.
  • Don't close the calendar while the user is still choosing the range end.

Accessibility

Keyboard

DatePicker keyboard
Keys Action
Enter or Space On the field, opens the calendar.
Arrow keys The binding must move between days by one day or one week.
Page Up or Page Down The binding must move to the same day in the previous or next month.
Home or End The binding must move to the first or last day of the week.
Enter or Space On a day, selects it; in date mode this closes the calendar.
Escape Closes the calendar and returns focus to the field.

Roles and names

  • The field has role="combobox", aria-haspopup="dialog", aria-expanded and aria-controls.
  • The popup is role="dialog" with aria-label="Choose a date"; the grid is role="grid" and needs aria-labelledby on the month heading.
  • Each day is a <button role="gridcell"> and needs a full date as its name, such as "Friday 14 August 2026"; selected days use aria-selected="true".
  • Today should carry aria-current="date"; disabled days use native disabled.
  • The previous and next month buttons have names; the month label should be a live region so changes are read.

Focus

  • On open, focus moves to the selected day, or today if none; the grid uses roving tabindex so it is one tab stop.
  • Tab moves between the month buttons, the grid and the footer controls.
  • On close, focus returns to the field.

Other requirements

  • Range days differ by fill only; start and end are also aria-selected, and the range should be stated in text, such as "9 to 15 Sep" (1.4.1).
  • Disabled days are struck through as well as greyed (1.4.1).
  • The a11y report notes the calendar overflows a 320px viewport (1.4.10) and outside-month days fail contrast in dark (1.4.3).
  • Day cells are 36px high, above the 24px minimum (2.5.8).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

DatePicker test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (6 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- datepicker --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

DatePicker package
Source css/classic/components/inputs.css
Specimens also use Box · Button · Card · Chip · Control · Field · Icon · Popover · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes