Components · Inputs
Date Picker
A calendar that opens from a date field. The user navigates by month and year at the top and selects a day from the grid; the field then shows the date as MM/DD/YYYY.
Figma source: Date Picker ↗Examples
Usage
Original Figma description & what changed
From Figma: The date picker component appears when the user focuses in on a DATE FORM ELEMENT. The controls at the top allow the use to find the date by month and year, while the grid below selects the date. The date selected from this component will show in the Form Element in the correct formatted text of MM/DD/YYYY.
What changed: The original describes the mechanics accurately and is still correct. Added what it omits: that the text field must remain typeable (a calendar-only date entry is slow for anyone entering a known date, and unusable for some keyboard users), that the format hint belongs in persistent help text, and the keyboard contract for the grid.
When to use it
- Always pair the calendar with a text field the user can type into directly. Typing beats twelve clicks back to a date last year.
- State the expected format in persistent help text —
MM/DD/YYYY. - Accept forgiving input:
4/1/26,04-01-2026and2026-04-01should all resolve. - Disable dates that are genuinely invalid — a start date after the end date — and explain why.
When not to use it
- Do not make the calendar the only way to enter a date.
- Do not use a date picker for a birth date or any far-past date; a plain text field is faster.
- Do not open the calendar on focus if the user is likely to type — open it from an explicit calendar button.
- Do not silently reformat what the user typed while they are still typing.
<input type="date"> is keyboard accessible, localised, and gets a
proper spinner on mobile with no JavaScript. Its downside is that its visual
presentation cannot be fully styled to match this system. Where the date field sits in
a dense form and visual consistency matters less than reliability, the native control
is the better trade.
Accessibility
- The calendar grid is a
role="grid". Arrow keys move by day, PageUp and PageDown by month, Home and End to the start and end of the week. - Each day button’s accessible name must be the full date — “6 April 2026”, not “6”.
- Escape closes the calendar and returns focus to the field without changing the value.
- Announce the month and year when it changes, so a user arrowing across a month boundary is not silently relocated.
- Mark today, and mark the selected date, with something other than colour alone.
Tokens consumed
| Token | Applied to | Resolves to |
|---|---|---|
--container-background | Calendar surface | --color-white |
--container-border | Calendar border | --color-gray-300 |
--pagination-selected-background | Selected day | --primary-brand-color |
--menu-hover | Day hover | --color-gray-200 |