Before using this component, confirm that your engineer has scope to submit their code to Labs.
A date picker allows people to select a single date or time.
Overview
A date picker is an input that allows users to select a past, present, or future date using a text field or by choosing the date from a calendar.
Anatomy
- Label: Explains what date to enter or select.
- Date field: Text field that allows for manual input of a formatted date.
- Date format hint: Hint text that gives an example of the date format.
- Calendar button: Control that opens and closes the calendar. Also helps to indicate its availability.
- Calendar: A popover where the date is selected.
- Month and year controls Allows for navigation through time frames.
- Week day: Labels that identify days of the week.
- Previous and next month controls: Allows forward or backward navigation one month at a time.
- Day: Days in the month.
Demo
Open the component in Figma.
When to use
Use a date picker in these scenarios:
- When asking for a date or time
- For scheduling tasks.
When not to use
Don’t use a date picker in these scenarios:
- When the date is well-known and can be more quickly typed, such as a birthday. For these cases, use a text field - date field variant.
Behaviors
States
Disabled
Date pickers can be displayed as disabled.
Read-only
Date pickers can be displayed as read-only. For example, in a larger UI that is locked by default but can be made editable with an action such as an edit button.
Error
An error state occurs when a user enters or selects a date that is outside of the date limits. For example, a campaign date in the future or too far in the past.
Wherever possible, selections outside the scope of an interaction should be unavailable to prevent errors.
Date picker calendar interactions
- When the month and year controls are collapsed, the chevron pointing down icon is used. When the controls are expanded, the chevron pointing up icon is used.
- When the year control is expanded, a menu list appears to select the year.
- After a date is selected in the calendar, the calendar closes.
- The calendar can also be closed by interacting outside of the popover.
- Until a date is selected or a user clicks outside of the popover, the picker will retain focus.
- Mobile full-screen pickers have an additional close affordance (X) icon button.
Internationalization
Date pickers are formatted to align to the style used by the locale (country and language) of the experience. Month/year or month/day/year will be rearranged in sequence of appearance.
Content guidelines
Label
- A label is required.
- Explain what the date selection refers to or is used for. For example, Start date.
- Be clear and descriptive.
- Don’t use a question as a label.
- Don’t use an instruction as a label. For example, Select a date.
Date format hint
- A date format hint is required for the simple date field. Don’t use a hint with a calendar date picker because the date format is automated by the calendar menu.
- Keep hint text as short as possible.
- The date format in the hint must also be translated. For example, some countries use month/day/year while others use day/month/year.
Default error messages
Calendar date picker
Select a date.
Simple date picker
Enter a date.
Content accessibility
Label attributes should be included for users who use screen readers to understand what the date picker relates to.