Skip to the page
TACTILE UI

Kit part · Calendars & date pickers · Inputs

Date picker

A date field with its calendar card in a slot underneath: type a date in any common form for your locale, or press the key and the card slides out. Single dates and ranges; shown the Intl way, posted as ISO.

Element
<tui-date-picker>
Needs
kit.css + kit.mjs
Rules
date-picker.rules.md · 5
Finishes
Aluminium · Graphite · Porcelain · Black
Volumes
Tactile · Quiet
On this page
  1. Variants
  2. Every state, at once
  3. API
  4. Markup
  5. Accessibility
  6. How it’s built
  7. Rules
  8. Related parts
01

Variants

Single date
Range · stays and holds
Locale · de-DE
Locale · en-US
02

Every state, at once

Both finishes, side by side. Hover, pressed and focus are forced with .is-hover, .is-down and .is-focus; checked and disabled are real.

Aluminium

PartRestFocusCard outError
Field
Session date
Session date
Session date
Session date
Type a date like 28 Sept 2026.

Graphite

PartRestFocusCard outError
Field
Session date
Session date
Session date
Session date
Type a date like 28 Sept 2026.
03

API

NameKindValuesWhat it does
labelattributerequiredThe printed label over the well; it names the field.
nameattribute—Adds a hidden input that posts the value as ISO: “2026-09-28”, or “start/end”.
valueattribute · propertyISO · "start/end"The committed date. Shown in the field the locale’s way.
modeattribute"range"Two dates. The card asks for the first day, then the last.
localeattributeBCP 47 · langHow dates are shown and read, and the week’s first day in the card.
min · maxattributeISO datesPassed to the calendar; typed dates outside get a hint naming the bounds.
disabled-weekdays · disabled-datesattribute"0 6" · ISO datesClosed days, in the card and when typed.
hintattributetextThe hint under the well when all is well.
requiredattribute—Marks the visible input required.
show() · close()method—Slide the card out, or back into its slot.
changeeventbubblesA date, or a whole range, was committed: typed or picked.
Enterkeyboardin the fieldRead what was typed. It accepts 28/09/2026, 28 Sept, Sep 28 2026, 2026-09-28 and the locale’s own ranges.
Alt+Downkeyboardin the fieldOpen the card (plain Down works in an empty field).
Escapekeyboardin the cardClose it and return to the calendar key.
Calendar keyskeyboardin the cardEverything the calendar takes: arrows, Home/End, PageUp/PageDown, Enter.
04

Markup

<tui-date-picker label="Session date" name="session" locale="en-GB"
  value="2026-09-28" min="2026-09-01" disabled-weekdays="0"></tui-date-picker>

<!-- A range: posts "2026-10-05/2026-10-09". -->
<tui-date-picker label="Hold Studio B" name="hold" mode="range"></tui-date-picker>
import '/kit/kit.mjs';   // defines <tui-date-picker> and <tui-calendar>

const picker = document.querySelector('tui-date-picker[name="session"]');
picker.addEventListener('change', () => price(picker.value));   // "2026-09-28"
picker.show();    // slide the card out from code
picker.close();

Needs kit.css and kit.mjs. How to install the kit.

05

Accessibility

  • A real text field with a <label>. The calendar key has aria-haspopup="dialog" and aria-expanded; the card is a non-modal role="dialog" with a name.
  • Opening moves the focus to the chosen day (or today) in the grid; picking returns it to the field, Escape to the key.
  • Errors set aria-invalid and rewrite the hint, which the field points to with aria-describedby, so the reason is read with the field.
  • In range mode a polite line in the card says what to pick next: the first day, then the last.
06

How it’s built

A custom element that writes a .tui-field (label, a recessed well holding the input and a small calendar key, a hint, a hidden ISO input) and a card holding a <tui-calendar>. Reading a typed date asks Intl for the locale’s order of day, month and year and for its month names (long and short, accents folded, English as a fallback), then checks the date is real; ranges are split on a dash or “to”, and missing months or years are borrowed from the other half, so Intl’s own range output (“10–14 Sept 2026”, “Sep 10 – 14, 2026”) reads back. The card slides out of the slot top first (a clip and a 10px drop over 200ms) and keeps an inner shadow on its top edge where the slot shades it.

07

Rules

date-picker.rules.mdIn the brain

The keyboard is never second-class: whatever a person types in their own format should just work.

5 rules in this file, with the foundations they rest on and the anti-patterns that break them. Full rules ship in the brain with the Pass.

08
September2026
14151617181920

Calendar

A month on a plate. The month and year sit on two drums behind a window and roll when you page; the chosen day is a latched cap, a range is a groove cut between two caps, and events are lamps named in the line below.

Field

Text entry in a recess, the label printed above it, and a hint that says how to fix an error.

Combo

One field with its one action in a shared well: subscribe, search, add.

Docs
Finish
Volume