DatePicker

A button or text field that picks one date from a Calendar in a popover.

Example
import { DatePicker } from "@elements/ui/date-picker";

<DatePicker value={form.due} />
<DatePicker value={form.due} input name="due" required />
<DatePicker value={person.dob} captionLayout="dropdown" startMonth="1900-01" max={today} />

Parts

Part	What it is
DatePicker	The picker: a trigger, a Popover with a Calendar, and a hidden input with the ISO value for the form.
.date-picker-trigger	The button (button mode). Its width holds across every date.
.date-picker-input	The text field (input mode): the locale's numeric format or ISO.
.date-picker-button	The calendar button inside the text field (input mode).
.date-picker-content	The popover panel: a dialog named by calendarLabel.
.date-picker-footer	The footer slot under the calendar.
.date-picker-value	The hidden input: name, required and validity. Beside the control with data-field-input, so a Field validates it; the only field the picker submits.
.date-picker-actions	Cancel and OK under the calendar (actions).

Attributes

Attribute	Type	Default	Description
value	ISODate (two-way)	""	The date, "YYYY-MM-DD".
open	boolean (two-way)	false	Whether the calendar is showing.
placeholder	string	""	Shown without a value: "Pick a date" for the button, the format hint for the field.
format	Intl.DateTimeFormatOptions	{ dateStyle: "long" }	How the button shows the date.
locale	string	""	BCP 47 tag for the text, the calendar and typed dates.
numerals	string	""	Numbering system for the text and the calendar.
calendar	string	""	An Intl calendar (persian, hebrew, ...) for the calendar, the text and typed dates; the value stays a Gregorian ISO date.
timeZone	string	""	An IANA time zone ("Pacific/Auckland"): today is the date there. Dates stay plain ISO days.
input	boolean	false	A text field you can type into, with a calendar button.
natural	boolean	false	Input mode reads English phrases: tomorrow, in 3 days, next friday, dec 25. The text stays as typed.
clearOnInvalid	boolean	false	Input mode: while the text is not an allowed date, the value is empty (the text stays). For a field driving an inline calendar.
actions	boolean	false	Cancel and OK under the calendar: OK picks the focused day (APG date picker dialog).
okLabel, cancelLabel	string	"OK", "Cancel"	The actions' text.
yearButtons	boolean	false	Previous and next year buttons in the calendar.
help	string	""	Keyboard help announced once focus rests on a day.
name	string	""	Form name; the form gets the ISO date.
form	string	""	The id of a form elsewhere on the page.
required	boolean	false	The form will not submit without a date.
disabled	boolean	false	Not interactive; not submitted.
readOnly	boolean	false	Shows the date and stays focusable (data-readonly); never opens. Not required, as a native read-only input.
invalid	boolean	false	aria-invalid and the danger border.
invalidMessage	string	"Enter a valid date."	The form's message for typed text that is not an allowed date.
size	"sm" | "md" | "lg"	"md"	Height and text from the control tokens.
block	boolean	false	Full width.
label	string	""	Accessible name without a visible label; the button appends the date.
calendarLabel	string	"Choose date"	Names the popover dialog and the calendar button.
changeLabel	string	""	Input mode: the calendar button's name once a date is set, "Change Date, <date>".
icon	boolean	true	A calendar icon in the button.
min	ISODate	""	Earliest date: earlier days disabled, navigation bounded, typed dates refused.
max	ISODate	""	Latest date.
disabledDates	Matcher | Matcher[]	false	Days that cannot be picked (Calendar matchers).
modifiers	Record<string, Matcher | Matcher[]>	{}	Calendar custom modifiers.
captionLayout	"label" | "dropdown" | "dropdown-months" | "dropdown-years"	"label"	Month and year dropdowns in the calendar.
numberOfMonths	number	1	Months in the popover.
showOutsideDays, fixedWeeks, showWeekNumber, weekStartsOn, isoWeek, startMonth, endMonth, today, dir	as Calendar	as Calendar	Passed to the Calendar.
month	ISODate	""	The month each open starts on; empty starts on the picked date. Browsing never writes it back.
defaultMonth, hidden, navLayout, hideNavigation, disableNavigation, reverseMonths, reverseYears, hideWeekdays, firstWeekContainsDate, broadcastCalendar, animate, labels, formatters	as Calendar	as Calendar	Passed to the Calendar. labels translates the month buttons, dropdowns and day names.
closeOnSelect	boolean	true	Picking a day, or clicking the picked day to clear it, closes the popover.
side	"top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"	"bottom"	Where the popover opens.
align	"start" | "center" | "end"	"start"	Alignment against the trigger.
modal	boolean	false	Focus trapped in the popover, the page hidden from assistive tech.
class	string	""	Classes on the root.
attrs	Record<string, string | number | boolean | undefined>	{}	Attributes for the button (or the text field in input mode): id, aria-*, data-*.
onValueChange	(value: ISODate) => void	() => {}	The picker changed the value.
onOpenChange	(open: boolean) => void	() => {}	The picker opened or closed itself.
onDayClick	(date, modifiers, e) => void	() => {}	From the Calendar.
onMonthChange	(month: ISODate) => void	() => {}	From the Calendar: the shown month changed.

Slots

Slot	Content
footer	Under the calendar in the popover: presets, a TimePicker, actions.

Keyboard

Keys	Action
Enter / Space	On the button: opens the calendar on the selected day, else today.
ArrowDown	In the text field: opens the calendar.
Enter	In the text field: commits the typed date, then the form submits it.
Arrows, PageUp / PageDown, Home / End	Move through the calendar (see Calendar).
Enter / Space on a day	Picks it, closes and returns focus to the button.
Escape	Closes without a change and returns focus.

Data attributes

Attribute	Values	On
data-mode	"button" | "input"	root
data-state	"open" | "closed"	root, trigger
data-empty	present without a value	.date-picker-trigger
data-readonly	present with readOnly	.date-picker-trigger

Accessibility

• The trigger has aria-haspopup="dialog", aria-expanded and aria-controls; the popover is a dialog named by calendarLabel.
• In input mode the calendar button is named "Choose date, October 14, 2026", and the field is described by the format hint (APG date picker dialog).
• Typed text that is not an allowed date sets aria-invalid on blur and a custom validity, so the form will not submit.
• Picking a day or pressing Escape returns focus to the trigger.
• The hidden value input is aria-hidden and out of the Tab order; when the browser reports it, focus goes to the visible control.

See also

• Calendar (opens in a new tab): A month grid for picking one date, several dates or a range, with keyboard navigation across months.
• DateRangePicker (opens in a new tab): A button that picks a start and end date from a two-month range Calendar in a popover.
• TimePicker (opens in a new tab): A time of day in the browser's own time field, styled as a control, with steps, limits and suggestions.