Date picker

 

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

Date Picker anatomy
  1. Label: Explains what date to enter or select.
  2. Date field: Text field that allows for manual input of a formatted date following the localized placeholder format.
  3. Hint text (optional): Provides additional help or context about the date being selected.
  4. Calendar button: Control that opens and closes the calendar. Also helps to indicate its availability.
  5. Calendar: A popover where the date is selected.
  6. Month and year controls Allows for navigation through time frames.
  7. Week day: Labels that identify days of the week.
  8. Previous and next month controls: Allows forward or backward navigation one month at a time.
  9. Day: Days in the month.

Demo

Storybook failed to load. Please connect to the VPN to access.

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

Limiting selectable dates

Your eng partner can use Min and Max date props to restrict dates so that only a specified range are selectable. The calendar will not accept inputs for dates outside of those dates. But, users can attempt to bypass the restriction by manually entering a date outside of the range. Your eng partner will need to build validation to prevent this.

 

Internationalization

Date pickers are formatted to align with 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.

Date picker Globalized

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.

If the user fails to make a selection for a required date picker:

Calendar date picker

Select a date.

Simple date picker

Enter a date.

 

If the user enters a date outside of the date range accepted by a simple date picker:

Minimum date

Date entered is earlier than allowed dates. Select a date from the range available in the calendar.

Maximum date

Date entered is later than the allowed dates. Select a date from the range available in the calendar.

 

Content accessibility

Label attributes should be included for users who use screen readers to understand what the date picker relates to.

 

Figma: Date picker

Coming soon

  • Internationalization: Full translation support for text elements.