Anatomy
- Label: Explains the purpose of the date Picker.
- Input: Shows the selected date and lets users type it manually.
- Popout: Opens on interaction, presenting the calendar for date selection.
- Month & Year select: Select controls that allow users to choose the displayed month and year.
- Navigation buttons: Buttons used to move to the previous or next month, allowing users to navigate through the calendar.
- Legend: A row displaying the abbreviated names or initials of the days of the week, helping users quickly identify columns.
- Days grid: The main area of the calendar showing the dates of the selected month arranged in a 7-column grid, where each cell represents a day.
Usage Guidelines
When to use this component
Choosing or editing a date inside of the form
Selecting a range of dates.
When not to use this component
- To navigate or browse the surface (e.g, Changing visible Calendar day). Use Calendar component instead.
-
For filtering purposes. Use Filter component instead.
Best Practices
Use labels to specify the data required in the input field.
Do not avoid labels as they are essential to the input completion and later understanding.
Use numeric dates when the space is limited. Different countries have different conventions and they can be confusing for international users.
Use the descriptive format when you have enough space and it is important to present more details about the date.
Use hints to provide useful information about the required input.
Do not duplicate information, if an error message is repeating the hint, hide the hint.
General Component Behaviors
Opening date picker
- Date picker popout opens when clicking on the input field or label. For range variant either input can open the popout
- If user focuses on the input, popout will not open unless user starts typing or click a bottom arrow key on the keyboard
Closing date picker
- Date picker popout closes when clicking outside of the input or popout area
- Date picker closes when users click esc button
- Date picker closes upon selecting a date. For range variant it closes after selecting the end range.
Responsive Behavior
Date Picker uses a bottom sheet on mobile and displays an overlay on top of the content. All interactive elements visually adapt their tap targets, and items include a bottom divider to clearly indicate separation between them.
States
Trigger
Component
Variants
Single date (default)
Allows for selecting a singular date.
Range
Allows for selecting a range of dates.
Content Guidelines
- Always pair the date picker with a clear, descriptive label that explains the purpose (“Visit date,” “Valid until”). Avoid vague labels like “Date.”
- Display and parse dates in the format appropriate for the user’s locale
- Where appropriate, prefill with today’s date or a sensible default to reduce effort.
- Make sure start and end fields are clearly distinguished (e.g, Valid from, Valid until).
- Consider using a placeholder text to hint at the required format.
- Make errors specific and actionable (e.g. ‘End date must be after start date’) so users know exactly how to fix them.
For further information, see the Content Styleguide.
Known Gaps
- Inconsistency in the state names.