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.
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.
- 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.
Open the component in Figma.
Use a date picker in these scenarios:
- When asking for a date or time
- For scheduling tasks.
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.
Date pickers can be displayed as disabled.
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.
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.
- 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.
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.
- 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.
- 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.
Calendar date picker
Select a date.
Simple date picker
Enter a date.
Label attributes should be included for users who use screen readers to understand what the date picker relates to.