Intro

The date picker lets users enter a single date and navigate directly from one month or year to another.

Inserting image..., Picture

Basic date picker

When to Use

Do

Use the date picker:

  • If users typically need to enter a single date.
  • To navigate directly from one month or year to another.
  • Тo enter a lot of data fast or primarily using the keyboard.

Don't

Don’t use the date picker:

  • If you need a combined date and time input component. In this case, use the date/time picker.
  • If you need to keep the calendar visible and prominent. In this case, use the calendar.
  • If users typically need to enter a date range. Use the date range picker instead.

Anatomy

  1. Date input field: The container in which a user enters data. It contains a mask.
  2. Text: A placeholder or selected/typed text.
  3. Date picker button: Button that opens the calendar.
  4. Calendar component

Picture

Anatomy of the date picker

Types

The date picker supports Gregorian, Japanese, Buddhist, Islamic and Persian calendars. You can use a single calendar type only, or show two calendar types – one primary and one secondary.

Single Calendar Type

The date picker supports Gregorian, Japanese, Buddhist, Islamic and Persian calendars.

Picture

Date picker with an Islamic calendar

Two Calendar Types

In addition to the primary calendar, you can add a secondary calendar type.

Picture

Date picker with a secondary calendar

Custom Placeholder

You can provide a custom placeholder text. By default, the placeholder text shows the specific date format (based on the user’s locale).

Picture

Date picker with a custom placeholder text

Restricted Date Range

You can set minimum and maximum dates. In this case, the user can only select dates within the approved range.

Inserting image..., Picture

Date picker with restricted date range

Behavior and Interaction

Selecting a Date

If the date picker is editable, the user can select a date in two ways:

To change the month, the user can either use the Previous/Next arrows or select a specific month in the month view.

To change the year, the user can either scroll through the months with the Previous/Next arrows or select a specific year in the year view.

Shortcuts

The following shortcuts are available for entering specific dates:

Restricted Date Range

If minimum and maximum dates have been set, selection and navigation to dates outside this range is disabled.

Formatting

When users enter a date in the input field, it must comply with the required date format. For instance, if the format pattern is yyyy-MM-dd, the user should input a date like 2015-07-30.

Supported format options are based on patterns using Unicode Locale Data Markup Language (LDML) date format notation.

guideline

Whenever possible, we recommend using the user's default date format for clarity and familiarity.

If technical constraints prevent supporting the default format, opt for a medium format instead. In most locales, the medium format displays four-digit years, like DD/MM/YYYY or MM-DD-YYYY, which helps users quickly identify the year.

Components

Implementation

Specifications

Components

Implementation