Updated: July 16, 2024

Date/Time Picker

Intro

The date/time picker allows users to select both the date (day, month, and year) and time (hours, minutes, and seconds).

Basic date/time picker – live example

When to Use

Do

Use the date/time picker:

  • If you need a combined date and time input component.
Don't

Don’t 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. Use the date picker instead.
  • If users typically need to enter a time. Use the time picker instead.
  • If users typically need to enter a date range. Use the date range picker instead.

Anatomy

  1. Date input field: Field for entering and displaying the date and time. It contains a mask.
  2. Date/time button: Button that opens the date/time dialog.
  3. Date picker: Used to select a localized date.
  4. Time picker: Used to select a localized time.
  5. Dialog footer with OK and Cancel buttons.
Anatomy of the date/time picker
Anatomy of the date/time picker

Variants

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

Basic Date Time Picker

Basic date/time picker – live example

Date/Time Format

Empty input field showing the date/time format – live example

Restricted Date Range

Date/time picker with a restricted date range – live example

Behavior and Interaction

Selecting a Date and Time

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

  • By typing in the input field.
  • By choosing a date from the calendar and time from the clock. After selection, the date/time picker closes and the date and time appear in the date input field.

Navigation

  • 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.
  • To change the time, the user can either choose a time on the clock or type in the specific time in time picker input field above the clock.

Shortcuts

By default, the system enters the current time.

The following shortcuts are available for entering specific dates:

  • “today”
  • “yesterday”
  • “in x days”
  • “x days ago”
  • “yesterday – today”
  • “x days ago – in x days”

Restricted Date Range

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

Formatting

If the user types the date in the input field, it must fit the required date format. For example, if the format pattern is “yyyy-MM-dd”, a valid user input would be “2015-07-30”.

The supported format options are pattern-based, and use the Unicode Locale Data Markup Language (LDML) date format notation.

Related Links

Implementation