DatePicker

An accessible date-picker with a calendar popover.

Category: inputs · WCAG 2.2-AA · date, calendar, picker, input, form

Sizes

States

default
open
error
disabled

Props

Prop	Type	Default	Description
`id`	`string`	—	Base id for the input and its popover/aria wiring; auto-generated when omitted.
`value`	`string`	—	Controlled ISO date value (YYYY-MM-DD)
`defaultValue`	`string`	—	Uncontrolled default value
`onValueChange`	`(value: string \| undefined) => void`	—	Called with the selected ISO date string (or undefined when cleared)
`min`	`string`	—	Minimum ISO date
`max`	`string`	—	Maximum ISO date
`clearable`	`boolean`	`false`	Shows a clear button
`typeable`	`boolean`	`true`	When true, the field accepts a typed date as well as one picked from the calendar.
`disabledDate`	`(date: Date) => boolean`	—	Rejects individual dates the bounds allow — holidays, weekends, taken slots.
`format`	`Intl.DateTimeFormatOptions`	—	Formatting options for the displayed date. Defaults to the locale's numeric form.
`showToday`	`boolean`	`false`	When true, the calendar offers a button that jumps to the current month.
`name`	`string`	—	Submitted with a surrounding form — a hidden input carrying the ISO value.
`required`	`boolean`	—	Marks the control as required for assistive technology.
`open`	`boolean`	—	Controlled open state of the calendar popup.
`onOpenChange`	`(open: boolean) => void`	—	Called when the popup opens or closes.
`label`	`string`	—	Visible field label rendered above the input; it also names the control.
`hint`	`string`	—	Hint text
`error`	`string`	—	Error message
`size`	`'sm' \| 'md' \| 'lg'`	`md`	Field size
`disabled`	`boolean`	`false`	Disables the picker
`labels`	`DatePickerLabels`	—	i18n label overrides
`aria-labelledby`	`string`	—	Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it.
`aria-describedby`	`string`	—	Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced.
`aria-invalid`	`boolean`	—	Wired automatically by a wrapping `Field` when it is in an error state.
`ariaLabel`	`string`	—	Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is visible; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this.

Design tokens

--cascivo-color-accent-text
--cascivo-color-surface
--cascivo-color-surface-overlay
--cascivo-color-border
--cascivo-color-border-strong
--cascivo-color-accent
--cascivo-color-text-on-accent
--cascivo-date-picker-day-today-color
--cascivo-color-text
--cascivo-color-text-muted
--cascivo-color-text-subtle
--cascivo-color-bg-subtle
--cascivo-color-destructive

When to use

Picking a single calendar date in a form where a visual month grid helps (due dates, bookings)
Date entry that benefits from min/max constraints and locale-aware formatting and week start

When not to use

Selecting a time of day — use TimePicker
Free-form or approximate dates where a plain Input is faster, or a date already known by typing

How to build an accessible DatePicker in React →

Examples

Basic

Uncontrolled date picker

<DatePicker label="Date" />

Clearable

With clear button

<DatePicker label="Date" clearable />

With constraints

Date range constraint

<DatePicker min="2024-01-01" max="2024-12-31" />

Related components

TimePicker — Combine when both a date and a time are needed
Input — Use a plain input when a calendar grid is unnecessary
Form — Typically a field within a form with label/hint/error

← Back to docs