Date Picker

To select a single date, users can open the calendar and press once on the desired date, or enter the date manually in the text input. Selection is indicated by a filled blue container.

The calendar opens as a dropdown menu when the user presses the calendar icon located next to its text input field. It opens top-left aligned and is attached to the input.

When adding two or more date pickers horizontally or stacked in a digital experience, it is important to apply the correct padding to ensure consistent alignment. In this case, the default is the same for large and small components.

Specifications for the component are measured in pixels and reflect the default layout as described in the form pattern. Any changes regarding density should follow form pattern layout guidance.

If the text input field has no value, the calendar will default to the current month and year. Clicking on a day selects its value and closes the calendar. Once a date is selected, opening the calendar again will show the month and year of the selected date. Pressing the today button will enter the current day into the input and close the calendar menu. This allows the user to quickly select today’s date.

You can select a month by pressing the month button, which will open a select list displaying all months, or using the pagination arrows.

Pressing the year button will open a list displaying a defined range of available years to choose from. Only include years within the range that help users make an appropriate selection. For example, scheduling an appointment should only be available for the same day or future dates. Pressing on a year preserves all other selections, but may reformat the calendar to align numeric dates with their respective days. The initial and final year for list should be provided via parameters. By default, the list includes a range from 1900 to 2100. Speak with your engineering team about limiting the range in your dropdown to match your use case. For example, scheduling should only include future, available dates. If you’re asking for a date of birth, the top of the range should not exceed the current year.

It is possible to make certain dates unavailable and therefore inactive in a date picker. In the Figma layers panel of your project, you can make dates inactive or "not available” visually. All exceptions must also be defined in code. Consult with your engineering team to determine which dates should be available for selection and which should be excluded. For more information, read about date picker in Storybook.

Make sure the label communicates the purpose of the date being entered
If the date being entered or chosen is specifically for a purpose (such as a start date), then that purpose should be placed in the label.
WCAG 2.1: 2.4.6 Headings and Labels, 3.3.2 Labels or Instructions

Ensure the date picker is operable by keyboard
The date picker, as any other component, needs to have a useful keyboard navigation for people who rely on a keyboard or assistive technology instead of a mouse to navigate. Users should be able to cycle between all interactive elements within the component by pressing the tab key, and be able to use the four arrow keys (up, down, left, right) on both the month and day and the date cell selector itself. When the month or day dropdown is activated, keyboard functionality should follow standard W3C combobox patterns.
WCAG 2.1: 2.1.1 Keyboard, 2.1.2 No Keyboard Trap

Make the required date format explicitly clear—either in the label or the helper text
Spell out the required date format for users. While placing this information in the helper text (such as “Use format DD/MM/YYYY”) is acceptable, bear in mind that it will become hidden if the calendar is open. When possible, place it in the label, such as “Start date (DD/MM/YYYY)”.
WCAG 2.1: 3.3.2 Labels or Instructions

Use meaningful copy for error text
The error message should provide relevant assistance in helping users fix errors. Rather than unclear helper text such as “Invalid date”, explain the format required, possibly with an example.
WCAG 2.1: 3.3.3 Error Suggestion

Use the date formatting most commonly expected by your audience
Depending on your location, the date order and formatting might vary, and could be separated by slashes (/), dashes (-) or another character, such as a period. Make sure that the chosen date format is expected, consistent for your audience, and clearly communicated.

Label
The label should clearly and succinctly explain the purpose of the date picker, providing contextual guidance and formatting when possible.
Do: Date of birth (MM/DD/YYYY)
Don’t: Date

Placeholder text
Do not rely on placeholder text to show formatting unless the formatting is applied as a mask within the input. Placeholder text disappears when the user begins typing, so they are unable to see the format for reference or for review. If applying a mask, ensure the date format is expected and consistent for your audience.
Do: __ - __ - ____
Do: – / – / ----
Don’t: MM/DD/YYYY

Helper text
Helper text can be used to show formatting, such as “Use format DD/MM/YYYY”. However, it is not preferred as opening the calendar will hide it from view.
Do: MM/DD/YYYY
Don’t: Enter a valid date