Date Picker

When to use

• A date whose calendar context matters. Day of week, distance from today or availability around it, picked from a compact trigger.
• Dates with limits or blocked days. Bounds, disabledDates and unavailableDates keep people from choosing a day that cannot work.
• Typed entry in forms with anchor="input": an invoice or start date people already know and would rather type. The calendar stays one Tab away. Single dates only; ranges keep the button.
• A range, several dates, or a date and time from one trigger: mode="range" with presets, mode="multiple", or the date-time Apply panel.
• A label that carries the format. Put format expectations in supportingText or the label, never placeholder-only: a placeholder disappears the moment a value exists. The input anchor puts the locale's format there by default.

When not to use

• For a calendar that stays on the page. Use Calendar: the same grid inline, no popover. Everything DatePicker forwards (markers, booked days, selection variants, the date-time panel) also works there directly.
• For a memorable, known date such as a date of birth. Typing a date you already know beats navigating to it, so use a plain Field. If you keep a picker for it, use the captionLayout="dropdown" recipe (see Date of birth) rather than making someone page back through hundreds of months.
• For a time alone. Use TimePicker; the built-in date-time panel covers date and time together.
• To choose among a handful of known dates, such as delivery slots. Use Select or Combobox rather than any-date entry.
• When people only have a relative time like "now" or "tonight". Offer it as an option in a Select, or as a preset.

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}
/>

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.

A multiple selection's summary follows the locale's plural rules: in Arabic, two dates, three to ten, and eleven or more each take their own form.

Sizes

Calendar cell density across sm, md, and lg — trigger, chips, panel fields and popup all follow. Trigger heights land on 32/40/48px with a mouse; on a touch screen the 44px touch floor raises sm and md to 44px while lg keeps its 48px, so the smaller two deliberately look alike there — 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 — timezone math belongs to the consumer, which alone knows what the date means.

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 a 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: on any touch screen, tablets included, the trigger is ≥44px (Button floor) and the clear button carries a 44px tap area on both anchors; 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 floors. On a 320px screen the popup keeps 1px from each edge so its 44px grid fits whole.
• AT matrix: VoiceOver + Safari passed 2026-09-14. The trigger reads "Jun 24, 2026 dialog pop up button". Space opens "Choose date web dialog", and ArrowRight lands on "Thursday, June 25th, 2026 button" inside "June 2026 table 7 columns, 5 rows". Enter closes it and the status region reads "Jun 25, 2026". NVDA and JAWS: UNTESTED on this machine.
• 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;
}