A Date Picker lets users select a date or range of dates. It uses a text field and a visual calendar in a popover.
- Autocomplete (not built)
- Button Group (not built)
- Checkbox Group
- Date Picker (not built)
- Empty State
- Filter Menu
- Global Notification
- Guidance Block
- Hero Card
- Icon Button
- Infinite Scroll (not built)
- Inline Notification
- Likert Scale Legacy
- Loading Placeholder
- Loading Skeleton (not built)
- Loading Spinner
- Pagination (not built)
- Progress Bar (not built)
- Progress Stepper
- Radio Group
- Rich Text Editor
- Search Field
- Split Button
- Tile Grid
- Toast Notification
- Date Pickers might include a single date or a date range.
- Date Pickers often require validation for the user's input.
- Choose good defaults, such as the current date, end of financial year, end of calendar year, or according to some other schedule, such as a company's feedback schedule.
- Help people prevent and recover from invalid dates by disabling some dates or providing validation feedback.
- Text Field label:
- Provide a descriptive label that conveys the purpose of the field. Aim to convey if it a single date or a date range is expected.
- Calendar icon:
- The calendar Icon shows that this is a date field and that the user may select a date from the visual calendar popover.
- Visual calendar:
- The calendar view itself shows selected dates in a visual calendar layout.
- Month and year:
- The month and year is shown on each month of the visual calendar.
- The visual calendar appears inside a Popover.
- Previous and next month buttons:
- In the popover, the previous and next buttons let people navigate one month at a time.
- Placeholder text:
- Below the Date Picker, placeholder text can be used to show the accepted date format or other supporting information.
To reduce the cognitive load and effort for users, pre-select a good default date. To choose a good default date, some options and considerations include:
- Today. This is an easy reference for many people.
- Significant calendar boundaries, such as the end of financial or calendar year.
- Significant dates for the customer, such as their existing feedback schedule.
- People science. We know typical time periods for collecting, understanding, and acting on feedback. We can use these date ranges.
Sometimes if it is necessary for the user to make a conscious choice, you might not provide a pre-selected good default. In that case, you'll need to provide clear and specific validation feedback.
Where it makes sense, provide text below the Date Picker to provide placeholder info about the accepted date format. Avoid using HTML
placeholder text to show date formats because it can be inaccessible to some people using screen readers. See the Product language style guide dates section for details on presenting date formats, such as
Mmm DD, YYYY.
For selecting a date far in the future or past compared to the default, you might consider using a Select component instead.
You might consider providing shortcut buttons that select specific relative dates if they are common choices.
When a user selects a single date, close the visual calendar.
When a user first selects a date, set the start date in the range.
When a user selects a second date, close the visual calendar.
To prevent errors, you might disable dates before or after dates that don't make sense. For example, an employee cannot start at a company before they are born, so for selecting a start date, you might disable dates before their date of birth. To do this, you might set a "min" date or a "max" date. See the Interaction states guidelines.
To help people recover from errors, you might instead allow dates that don't make sense and then show validation errors so people know what they need to change. Sometimes it can be easier to make a minor adjustment to an incorrect date than to start over. For example, if the user has selected the right month but was off by 1 day, it might be easier to adjust it by 1 day than to have that date rejected and need to select the month and day again.
By default, we immediately update the date value when a user selects the date or dismisses the visual calendar popover, a little like autosaving. For some circumstances, you might instead choose to provide "Update" and "Cancel" buttons in the popover if the risk and impact of errors is high. For example, if selecting the wrong date as a filter for some data would immediately cause the data to reload and performance is an issue, you might choose to include buttons to prevent frustration with slow interfaces.
All text used in the Date Picker, including the calendar days, month, year, buttons, and text field, needs to be localized. For more information, see the Localization guidelines.
We show weeks starting on Sundays.
Some people might find using a Date Picker difficult. Let people use the text field or visual calendar to select dates.
See WAI ARIA: Date Picker Dialog Example for more details.
- Show the visual calendar popover when a person using a mouse clicks on the Text Field label or input.
- Show the visual calendar popover when a person using a keyboard presses enter or space while the Text Field has focus.
- Let people tab forward and backward through the previous month button, next month button, and the visual calendar dates.
- When the focus is in the calendar, let people move keyboard focus between dates using the arrow keys.
- Let people press the enter key to select the date that has focus.
- Let people press escape to close the visual calendar popover without choosing a date and return focus to the Text Field.
- Focus indicator
- See Interaction states guidelines for focus indicators.
- Show focus indicator when interacting with the date range text field.
- Focus indicator progresses into the individual date picker elements when you navigate/ click around.
When the Date Picker has an error, show the error Text Field state and provide a meaningful validation error message that tells people how to recover from the error.
- Valid dates:
- You may need to validate that the date makes sense for its context.
- Valid formatting or input:
- You may need to validate to make sure the input is not garbage.
- Required dates:
- You may need to validate to make sure the user has selected a required date.
For selecting a date and time, use a Date Picker and adjacent Time Picker using a Text Field.
The resulting value in code for a selected date includes the year, month, and day, but not the time.
On mobile devices, you might choose to use a native date picker component instead of the visual calendar popover.
- Use a Date Picker when it's more efficient that typing a date in a Text Field.
- Use a Date Picker when the date to be selected will be within a year of the default date.
Here are some examples from elsewhere:
On this page
- To keep in mind
- When to use and when not to use
- External links