# Date and time picker

Takes a calendar day or a time of day, typed or picked from a month calendar or a list of times.

* Kind: component
* Name: DatePicker
* Page: https://design.werklist.com/components/date-picker
* Version: 2.1.2

## When to use it

* One day: a start date, a passport expiry, an interview
* A period, as two fields labelled Start and End
* A time of day, with the time field

## When not to use it

* A date shown in figures only, such as 09/10/2026
* A year in two digits
* A calendar as the only way to reach a day far from today

## Rules

* A date without a time is a calendar day, stored and shown without a time zone
* A period is two fields. The End calendar opens on the month of the start and offers no earlier day
* Slots are 30 minutes apart, or 15 when the task needs it

## Anatomy

* Field: a text field with a 32 px icon button at its end, named Choose date, holding a 16 px calendar icon (--input-border)
* Calendar: 284 px wide, narrower in a small window, padding 12 px, corner radius 12 px (--glass-fill-raised)
* Calendar shadow: the raised shadow, with a top highlight and a fine ring in dark (--glass-shadow-raised)
* Header: the month and the year, 14 px on 20 px, weight 700, between 32 px buttons for the previous and the next month (--text)
* Weekday row: short day names in the reader's language, 11 px on 16 px, weight 500, 4 px above the days, Monday first (--text-muted)
* Day: 36 px high, as wide as its column, corner radius 8 px, 14 px aligned figures, in seven columns 2 px apart (--text)
* Day under the pointer: a light fill (--glass-fill-hover)
* Day in focus: a 2 px ring of the brand blue at 40 percent (--brand-blue)
* Chosen day: the brand fill with white figures at weight 700 (--brand-true)
* Today: a 4 px dot in the brand colour, 4 px above the bottom of the day, hidden on the chosen day (--brand-true)
* Day that cannot be chosen: faded to 30 percent, with aria-disabled
* Days of other months: left blank
* Time list: slots every 30 minutes from 08:00 to 21:00, under the headings Morning, Afternoon and Evening in 11 px on 16 px, with the rows of the combobox (--text)

## Sizes

* md: height 44 px
* lg: height 48 px

## States

* Field states: As the text field, with no hover state (--input-border, --brand-blue, --error)
* A date the field cannot read: The text is kept, and the error gives an example: Enter a date like 28 Sep 2026. (--error)
* Touch screen: The device's own date or time picker takes the place of the calendar and the list

## Keyboard

* Left and Right arrows: Previous and next day
* Up and Down arrows: Same day of the previous and next week
* Home and End: First and last day of the week
* Page Up and Page Down: Previous and next month
* Shift+Page Up and Shift+Page Down: Previous and next year
* Enter or Space: Chooses the day and closes
* Escape: Closes without a change. Focus returns to the calendar button
* Tab: Moves between the month buttons and the grid. One day is in the tab order

## Accessibility

* The calendar is a dialog with aria-modal="true", named after the field label
* The month is a grid. Each day is a button named with its full date
* aria-selected="true" on the chosen day, and aria-current="date" on today
* The month heading is announced when it changes
* With reduced motion the calendar only fades, and months do not slide

## Content

* Display: the day, the short month and the full year in the reader's language, such as 28 Sep 2026
* Input: the day first with dots, slashes or spaces, the month by name, or year, month and day in that order. The year is written in full
* Clock: 24 hour, or 12 hour when the person's settings say so
* Time zone: named in the hint when readers in more than one zone see the value

## Tokens

* --glass-fill-input
* --input-border
* --glass-fill-raised
* --glass-shadow-raised
* --glass-fill-hover
* --brand-blue
* --brand-true
* --on-brand
* --text
* --text-muted
* --radius-lg
* --radius-xl
* --space-1
* --space-3
* --layer-popover