Skip to main content

Date picker

Overview​

Date pickers let users select a date.

Use when

  • Entering a memorable date such as a birthday, anniversary, credit card expiration date, license date.
  • Entering a date in the near future or recent past.
  • Users know the day of the week or week of the month instead of the numeric date.
  • Users need to be able to see dates in relation to other dates.

The date picker allows users to manually type in a date (useful for familiar dates) or select from a calendar dropdown (useful for scheduling). The date picker can handle formatting for manual entry on dates.

Text field with formatted mask.

The date picker formats dates that are entered manually.

Anatomy​

The date picker appears as a dropdown and is comprised of the following parts:

Anatomy of a date picker

  1. Text field input. Allows for text entry or tapping the date picker icon to open the date picker dropdown.
  2. Date picker icon. Opens and closes the date picker menu.
  3. Month and year selector. Users may tap the month or year to change them, or use the paginators to scroll through previous and next months.
  4. Selected date.
  5. Hover state.
  6. Today's date.

Validation​

Date pickers use the same styling for validation as text fields. Errors may include a date that contains too many or too few digits to be understood or a required field left blank, for example.

Internationalization​

Internationalization, also referred to as globalization, refers to software adapting to different languages, regional peculiarities, and technical requirements of a target locale without additional code changes. This means that if the location is known, then formatting of a date or time can automatically change to the acceptable local format.

Use the value attribute to customize how a date is formatted.

Accessibility​

The date picker is accessibility and may be fully utilized by keyboard only.

Responsive​

In desktop contexts, the date picker displays as an inline dropdown.

On mobile, and in web responsive apps displayed on mobile devices, the date picker component can be used instead of the native date pickers.

If the component is not available to be used, the native Android date picker or native iOS date picker can be used.

Date picker being used on mobile.

The date picker displays similarly on mobile as it does on desktop.

Best practices​

check_circle_outline

Use format masking to correct for formatting differences.

check_circle_outline

The date picker input width should match the width of the expected input.

cancel

Don't stretch the width of the date picker be the full width of a form; the width of the field should match the width of the expected input.

cancel

Don't use separate fields for day, month, and year.

Components​

Patterns​

  • Date pickers may be used in forms