Date Picker

Playground

Installation

pnpm add @tessinaui/ui react-day-picker

Usage

import { DatePicker, createRangePresets } from "@tessinaui/ui";

{/* Single date with the field model */}
<DatePicker
  mode="single"
  label="Departure"
  required
  clearable
  selected={date}
  onSelect={setDate}
  errorMessage={error}
/>

{/* Date range with presets sidebar */}
<DatePicker
  mode="range"
  selected={range}
  onSelect={setRange}
  presets={createRangePresets()}
  numberOfMonths={2}
/>

{/* Typed input — type the date, or open the calendar button */}
<DatePicker
  mode="single"
  anchor="input"
  label="Departure"
  selected={date}
  onSelect={setDate}
/>

When to use

• DatePicker — picking a date whose calendar context matters (day of week, distance from today, availability around it), from a compact trigger.
• Calendar — the same grid inline on the page, no popover. Everything DatePicker forwards (markers, booked days, selection variants, the date-time panel) also works there directly.
• Plain Fields — memorable, known dates (date of birth on a form): GOV.UK's research is blunt that a calendar hurts there. If you keep a picker for it, use the captionLayout="dropdown" recipe below rather than making someone page back 400 months.
• TimePicker — time alone; the built-in date-time panel covers date + time together.
• Select / Combobox — choosing among a handful of known dates (delivery slots) rather than any date.
• anchor="input" — forms where people already know the date and would rather type it (an invoice date, a start date). The calendar stays one Tab away. Single dates only; ranges keep the button.

Format expectations belong in supportingText or the label — never placeholder-only (it disappears the moment a value exists). The input anchor puts the locale's format there by default.

Examples

Default

A single date picker with a calendar icon trigger.

Typed input

anchor="input" turns the field into a text input. Type the date in the locale's order — slashes, dashes, dots or spaces all work, and 2026-06-24 does too — and it's read when you press Enter or leave the field; nothing is masked while you type. The calendar button beside it is its own tab stop and the only way to open the popup. The format sits in the helper row until you set supportingText. Text that can't be read, or a day outside the bounds, shows an error and leaves the value alone — try 24.06.2026 in the first field, then 12/31/2025.

Labels and helper text

The input-family field model: visible label (top or start), optional marker, supporting text — all wired into the trigger's accessible name and description.

Validation

required marks the trigger and the calendar (the selection can't be emptied); errorMessage replaces the supporting text, implies the error intent and is announced politely. intent="warning" paints the boundary without the error semantics.

States

disabled, readOnly (focusable, popup stays closed) and isLoading (read-only semantics + aria-busy + spinner in place of the calendar icon).

Clearable

An in-trigger × clears the value, returns focus to the trigger, and answers Escape on the closed trigger. Follows Field's clear-button conventions, tab stop included.

Range

Range selection with two months side by side. A fresh range closes the popover after the end date; adjusting one endpoint of an existing range keeps it open for further browsing.

Range limits

min / max bound the number of nights; excludeDisabled resets a range that would swallow a disabled day.

Multiple

Multiple selection stays open across picks and summarises the trigger ("3 dates selected"); formatValue overrides the summary.

Presets

Preset shortcuts in a left sidebar (or a top strip). Picking one commits and closes — unless an Apply footer is present, in which case presets only set the selection (preview-style) and Apply commits.

Date & time

The calendar's own Apply panel (one implementation for Calendar and DatePicker): start/end date and time fields, optional timezone select, localized labels. Apply reports a CalendarApplyData and closes the popover.

Date of birth

captionLayout="dropdown" + bounds turns paging into month/year menus — the far-past navigation recipe.

Markers and legend

The calendar's markers (intent dots that extend day accessible names), showLegend, and the auto-hiding Today button — all through the popover.

Booked and blocked days

unavailableDates renders reachable-but-taken days (struck through, focusable, announced, unselectable); disabledDates removes days from reach entirely.

Selection variants

The calendar's selection inks: outline (habit-tracker ring) and line (hotel-style underline range).

On-color

tone="on-color" (set directly or inherited from a Surface) swaps the trigger onto the shared ink-well recipe; the popover itself stays a standard floating surface, per the family rule.

Locale and RTL

locale drives the trigger label (via Intl.DateTimeFormat, range labels via formatRange), the calendar, and the panel; dir="rtl" defaults the locale to Arabic. When dir is unset nothing is stamped — the component no longer forces ltr.

Sizes

Calendar cell density across sm, md, and lg — trigger, chips, panel fields and popup all follow. Trigger heights land on 32/40/48px on desktop; on phones the §5 touch floor raises sm and md to 44px while lg keeps its 48px, so the smaller two deliberately look alike below md — open one to see the cell density differ.

Loading

DatePickerSkeleton for content that isn't there yet; isLoading for a known value that's busy.

API Reference

Selection

Field

Trigger

How the input anchor reads a date. Fields go in the locale's order (MM/DD/YYYY en-US, DD.MM.YYYY de-DE, YYYY/MM/DD ja-JP) — a month/day swap is never guessed. A four-digit first field is read as year-month-day in any locale. Two-digit years pivot at 30 (26 → 2026, 30 → 1930); three-digit years are rejected as typos. The field is always Gregorian, and it reads the locale's own digits and punctuation, so it can always read back what it shows.

Calendar options

Presets

Date & time panel

Values are plain local Dates — the timezone select reports a choice in the Apply payload and never converts the dates (the Mantine/Astryx stance; timezone math belongs to the consumer).

Popover

Keyboard

Accessibility

• Pattern. A button trigger (aria-haspopup="dialog") opening a named non-modal dialog (role="dialog" from Base UI Popover, aria-label per mode — "Choose date" / "Choose date range" / "Choose dates", localized). The APG date-picker-dialog pattern is followed for focus and keyboard, with React Aria's non-modal popover stance instead of aria-modal — no modality is claimed that isn't enforced.
• Input anchor pattern. anchor="input" renders a plain text input (no combobox role — it owns no listbox) and a separate calendar button that is its own tab stop and the only popup entry, the APG date-picker-dialog shape. Unlike Combobox's trigger, which leaves the tab order because ArrowDown opens its list, this button has to stay reachable: a text input has no other keyboard path to the calendar. On close, focus returns to the button.
• Initial focus lands on the selected day, else today (react-day-picker autoFocus), not the first nav button.
• Names. With a label, the button trigger's accessible name is label + current value ("Departure Jun 24, 2026"), so the value is announced from the collapsed state; data-empty marks the placeholder state. The input anchor is named by its <label> and announces its own value; its calendar button reads "Choose date, Jun 24, 2026" once a value is set. Helper/error text rides aria-describedby; the error swap happens inside one polite region.
• One live region. A wrapper-level role="status" announces the committed selection (localized, formatRange-deduplicated). The calendar's own caption region announces month changes. No nested regions.
• On the button anchor, aria-invalid and aria-required are deliberately absent — neither is a supported attribute on role="button" (axe critical); the error state rides the described-by message, the intent boundary and data-invalid, and required rides the label name. The input anchor stamps both natively: they are legal on a real input.
• Touch targets: trigger ≥44px on phones (Button floor); the input anchor's field floors at 44px and its text at 16px, so iOS does not zoom on focus (the Button type ladder only applies to the button anchor); day cells and panel controls follow the calendar's TES-23 floors.
• AT matrix: VoiceOver verified locally. NVDA and JAWS: UNTESTED on this machine — status stays beta until a pass is on record.
• Known limitation. readOnly/isLoading triggers expose aria-disabled (a read-only button has no native state); the value stays in the name.

Agent notes

Stable hooks: data-slot="date-picker" (wrapper, data-mode, data-anchor="button" | "input"), date-picker-input-shell and date-picker-input (input anchor — its calendar button keeps date-picker-trigger), date-picker-trigger (data-empty/data-invalid/data-readonly/data-loading), date-picker-value, date-picker-clear, date-picker-popup, date-picker-presets, date-picker-label, date-picker-supporting, date-picker-announcer, date-picker-footer, plus every calendar-* slot inside the popup. The trigger also carries Base UI's data-popup-open while open.

Migration

PresetItem / DateRange

import { createSinglePresets, createRangePresets } from "@tessinaui/ui";
import type { DateRange, PresetItem } from "@tessinaui/ui";

interface PresetItem {
  label: string;
  getValue: () => Date | DateRange;
}