Intro

The date range picker allows users to enter a date range by either typing two dates in the input field or selecting a date range in the calendar.

The date range picker can also be used to enter a single date.

Picture

Basic date range picker

When to Use

Do

Use the date range picker if:

  • Users need to enter a date range and you know that the keyboard is not the primary device used for navigating the app.

Don't

Don’t use the date range picker if:

  • Users need to enter a date and a time. In this case, use the date picker or time picker instead.
  • Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
  • If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to jump quickly from field to field.

Anatomy

  1. Date input field: Field for typing in dates directly. It contains a mask.
  2. Text: A placeholder or the selected/typed text.
  3. Date range picker button: Button that opens the calendar.
  4. Calendar: See the calendar guideline for more details.
  5. Current date
  6. Selected date range

Picture

Anatomy of the date range 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.

Restricted Date Range

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

Picture

Minimum/maximum dates, specific date format

Predefined Date Range

You can set a predefined date range that is selected by default when the user opens the calendar. The user can still change the dates.

Picture

Predefined date range, custom delimiter

Behavior and Interaction

Selection

Date range: After selecting a start date, hovering over another date turns the dates in between to light blue, indicating that they are in the selected range. When the user selects an end date, the calendar closes and the range appears in the date input field.

Single date: To enter a single date, the user can type one date into the input field, or select the same day as the start and end date in the calendar.

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