Skip to contentSkip to navigation
DocsDocs

DatePicker

A field that opens a calendar to choose a date, or a date and time, and the calendar on its own.

StableSince 1.0.0
On this page

Overview

Show code, PublishDate.tsx

Calendar: the month the field opens.

Show code, PlanningCalendar.tsx

Variants

A day

A day; choosing one closes the calendar. The default.

A day and a time

A day and a time, with Now and the time's wheels.

Show code, Variants.tsx

In a toolbar

A field without a visible label, such as in a toolbar, shows its placeholder instead, and keeps enough width for a date.

Show code, SmallToolbar.tsx

Anatomy

  1. Field

  2. Control

  3. Label

  4. Value

  5. Clear

  6. Calendar icon

  7. Description

Show code, DatePickerAnatomy.tsx

  1. Popup

  2. Previous month

  3. Month

  4. Next month

  5. Day

  6. Actions

Show code, DatePickerPopupAnatomy.tsx

Behaviour

States

A read-only field shows its value, and its calendar doesn't open.

A date and a time

With a time, the calendar stays open beside the time's wheels, and turning a wheel sets the time at once.

Show code, MeetingTime.tsx

Within a range

Days outside the allowed range are unavailable, and the month buttons stop at them.

Show code, WithinRange.tsx

Rules

Ask for a time only where it matters, and for a range in two fields.

Use it when

  • A day, such as when a report goes out or a task is due
  • A day and a time, such as when a meeting starts
  • A day chosen from a month that stays in view, such as in a planning viewCalendar
DoA day alone where the time doesn't matter.
Show code, DayOnly.tsx
Don’tA time nobody chose, such as midnight on a due date.
Show code, NeedlessTime.tsx

Ranges

Use two fields for a range, such as First day and Last day.

Accessibility

KeyAction
Enter, Space, ↓, ↑ on the fieldOpens the calendar at the chosen day, or today.
←, →Moves a day, in the reading direction.
↑, ↓Moves a week.
Page Up, Page DownMoves a month; with Shift, a year.
Home, EndMoves to the start or end of the week.
Enter, Space on a dayChooses the day.
↑, ↓ on a time wheelChooses its previous or next value.
EscCloses the calendar and returns focus to the field.
Backspace, Delete on the fieldClears a clearable field.

Related

  • A time of day without a date, such as when a shift starts.

  • A month without a day, such as a billing period.

  • A moment shown relative to now, such as "3 hours ago".

  • A free-text date that people type in any format.

  • A choice among a few named periods, such as This week or This month.