Date Picker

Accessible, unstyled date picker: a segmented DateField plus a popover Calendar.


Package	`@vizejs/ui/date-picker`
Maturity	stable
Own the source	`vize lib pull date-picker`
Requires	calendar, context, controllable-state, date-field, id, popover
Aliases	datepicker, date popover, calendar input
Covers	WAI-ARIA APG date picker dialog, React Aria DatePicker, Reka UI DatePicker, HTML input type=date

Usage

import { DatePicker, DatePickerRoot, DatePickerCalendar, DatePickerContent, DatePickerField, DatePickerTrigger, DatePickerArrow, DatePickerGrid, DatePickerHeading, DatePickerMonthSelect, DatePickerNext, DatePickerPrev, DatePickerYearSelect } from "@vizejs/ui/date-picker";

Or copy the source into your project with vize lib pull date-picker (see Source Distribution).

API

`DatePicker`

Source: src/families/date-time/date-picker/date-picker-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned base id; nullish values use a deterministic fallback.
`modelValue`	`PlainDate \| null`	`undefined`	Controlled date; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`PlainDate \| null`	`null`	Initial uncontrolled date.
`open`	`boolean`	`undefined`	Controlled popover open state; `undefined` selects uncontrolled mode.
`defaultOpen`	`boolean`	`false`	Initial uncontrolled open state.
`modal`	`boolean`	`false`	Make outside content inert and contain focus while open.
`min`	`PlainDate \| null`	`undefined`	Earliest selectable date, inclusive.
`max`	`PlainDate \| null`	`undefined`	Latest selectable date, inclusive.
`isDateUnavailable`	`DateMatcher`	`undefined`	Predicate for dates that cannot be selected.
`locale`	`string`	`undefined`	BCP 47 locale for the field and calendar; defaults to the nearest LocaleProvider.
`dir`	`"ltr" \| "rtl"`	`undefined`	Text direction; defaults to the nearest LocaleProvider.
`today`	`PlainDate \| null`	`undefined`	Explicit current date for the calendar; the SSR-safe way to mark today.
`now`	`DateTimeNow`	`undefined`	Injectable clock evaluated during setup on server and client.
`timeZone`	`string`	`undefined`	IANA time zone used with `now` and host clocks.
`disabled`	`boolean`	`false`	Disable the field, trigger, and calendar.
`readOnly`	`boolean`	`false`	Lock the value while the calendar stays browsable.
`required`	`boolean`	`false`	Mark the field as required.
`name`	`string`	`undefined`	Hidden input name that submits the ISO date with forms.
`closeOnSelect`	`boolean`	`true`	Close the popover after a calendar selection.

Events

Event	Payload	Description
`update:modelValue`	`[value: PlainDate \| null]`	Fired when the picker requests a new controlled date.
`change`	`[value: PlainDate \| null, previous: PlainDate \| null, nativeEvent: Event \| null]`	Fired after a distinct committed date with the previous date and triggering event.
`update:open`	`[value: boolean]`	Fired when the picker requests a new controlled open state.
`open-change`	`[value: boolean, previous: boolean, nativeEvent: Event \| null]`	Fired after any distinct open-state request.

Slots

Slot	Slot props	Description
`default`	`DatePickerSlotState`	Picker composition: DatePickerField, DatePickerTrigger, DatePickerContent, DatePickerCalendar.

Exposed

Member	Type	Description
`value`	—
`open`	—
`disabled`	—
`readOnly`	—
`state`	—
`setValue`	—
`setOpen`	—

`DatePickerRoot`

Source: src/families/date-time/date-picker/date-picker-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned base id; nullish values use a deterministic fallback.
`modelValue`	`PlainDate \| null`	`undefined`	Controlled date; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`PlainDate \| null`	`null`	Initial uncontrolled date.
`open`	`boolean`	`undefined`	Controlled popover open state; `undefined` selects uncontrolled mode.
`defaultOpen`	`boolean`	`false`	Initial uncontrolled open state.
`modal`	`boolean`	`false`	Make outside content inert and contain focus while open.
`min`	`PlainDate \| null`	`undefined`	Earliest selectable date, inclusive.
`max`	`PlainDate \| null`	`undefined`	Latest selectable date, inclusive.
`isDateUnavailable`	`DateMatcher`	`undefined`	Predicate for dates that cannot be selected.
`locale`	`string`	`undefined`	BCP 47 locale for the field and calendar; defaults to the nearest LocaleProvider.
`dir`	`"ltr" \| "rtl"`	`undefined`	Text direction; defaults to the nearest LocaleProvider.
`today`	`PlainDate \| null`	`undefined`	Explicit current date for the calendar; the SSR-safe way to mark today.
`now`	`DateTimeNow`	`undefined`	Injectable clock evaluated during setup on server and client.
`timeZone`	`string`	`undefined`	IANA time zone used with `now` and host clocks.
`disabled`	`boolean`	`false`	Disable the field, trigger, and calendar.
`readOnly`	`boolean`	`false`	Lock the value while the calendar stays browsable.
`required`	`boolean`	`false`	Mark the field as required.
`name`	`string`	`undefined`	Hidden input name that submits the ISO date with forms.
`closeOnSelect`	`boolean`	`true`	Close the popover after a calendar selection.

Events

Event	Payload	Description
`update:modelValue`	`[value: PlainDate \| null]`	Fired when the picker requests a new controlled date.
`change`	`[value: PlainDate \| null, previous: PlainDate \| null, nativeEvent: Event \| null]`	Fired after a distinct committed date with the previous date and triggering event.
`update:open`	`[value: boolean]`	Fired when the picker requests a new controlled open state.
`open-change`	`[value: boolean, previous: boolean, nativeEvent: Event \| null]`	Fired after any distinct open-state request.

Slots

Slot	Slot props	Description
`default`	`DatePickerSlotState`	Picker composition: DatePickerField, DatePickerTrigger, DatePickerContent, DatePickerCalendar.

Exposed

Member	Type	Description
`value`	`PlainDate \| null`	Committed date.
`open`	`boolean`	Whether the calendar popover is open.
`disabled`	`boolean`	Whether the picker is disabled.
`readOnly`	`boolean`	Whether the value is locked while the calendar can still be browsed.
`state`	`PickerOpenState`	Stable open-state token.
`setValue`	`(value: PlainDate \| null) => boolean`	Request a value; returns whether it differs.
`setOpen`	`(value: boolean) => boolean`	Request an open state; returns whether it differs.

`DatePickerCalendar`

Source: src/families/date-time/date-picker/date-picker-calendar.vue

Props

Prop	Type	Default	Description
`numberOfMonths`	`number`	`1`	Number of consecutive months rendered.
`pagedNavigation`	`boolean`	`false`	Move month controls by `numberOfMonths`.
`fixedWeeks`	`boolean`	`false`	Always render six week rows per month.
`weekStartsOn`	`Weekday`	`undefined`	First day of week (`0` = Sunday); defaults to the locale preference.
`weekdayFormat`	`CalendarWeekdayFormat`	`"short"`	Weekday column label width.
`calendar`	`string`	`undefined`	Intl calendar used for display labels only.
`numberingSystem`	`string`	`undefined`	Intl numbering system for labels.
`ariaLabel`	`string`	`undefined`	Accessible name for the calendar group.

Slots

Slot	Slot props	Description
`default`	`CalendarSlotState`	Calendar composition; defaults to a header plus one grid per month.

`DatePickerContent`

Source: src/families/date-time/date-picker/date-picker-content.vue

Props

Prop	Type	Default	Description
`placement`	`Placement`	`"bottom-start"`	Preferred placement before collision handling.
`initialFocus`	`() => HTMLElement \| null \| undefined`	`undefined`	Initial focus target; defaults to the roving calendar day.
`ariaLabel`	`string`	`undefined`	Accessible dialog name.
`ariaLabelledby`	`string`	`undefined`	Ids that label the dialog.

Slots

Slot	Slot props	Description
`default`	`Record<string, never>`	Popover body, typically DatePickerCalendar.

`DatePickerField`

Source: src/families/date-time/date-picker/date-picker-field.vue

Props

Prop	Type	Default	Description
`placeholderValue`	`PlainDate \| null`	`undefined`	Date whose segments seed arrow-key stepping from empty; defaults to the picker `today` or host date.
`placeholders`	`FieldSegmentPlaceholders`	`{ year: "yyyy", month: "mm", day: "dd" }`	Placeholder text for empty segments.
`emptyText`	`string`	`"Empty"`	Text announced for empty segments.
`ariaLabel`	`string`	`undefined`	Accessible name for the segment group.
`ariaLabelledby`	`string`	`undefined`	Ids that label the segment group.
`ariaDescribedby`	`string`	`undefined`	Ids that describe the group and every segment.
`ariaErrormessage`	`string`	`undefined`	Id of the validation message used while invalid.
`ariaInvalid`	`boolean`	`false`	Force the invalid state.

Slots

Slot	Slot props	Description
`default`	`DateFieldSlotState`	Extra content after the segments, typically DatePickerTrigger. Receives field state.
`segment`	`FieldSegmentState`	Segment content. Receives the segment state; defaults to its text.

Exposed

Member	Type	Description
`focus`	—

`DatePickerTrigger`

Source: src/families/overlays/popover/popover-trigger.vue

Props

Prop	Type	Default	Description
`type`	`"button" \| "reset" \| "submit"`	`"button"`	Native button submission behavior.
`disabled`	`boolean`	`false`	Remove the trigger from activation and sequential keyboard focus.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label supplies one.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the trigger toggles the popover. Call `preventDefault()` to keep state unchanged.

Slots

Slot	Slot props	Description
`default`	`PopoverSlotState`	Trigger contents. Receives the current Popover state and trigger availability.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—

`DatePickerArrow`

Source: src/families/overlays/popover/popover-arrow.vue

Slots

Slot	Slot props	Description
`default`	`PopoverArrowSlotState`	Decorative arrow contents. Receives coordinates for optional custom drawing.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`x`	—
`y`	—

`DatePickerGrid`

Source: src/families/date-time/calendar/calendar-grid.vue

Props

Prop	Type	Default	Description
`monthIndex`	`number`	`0`	Zero-based index of the visible month this grid renders.
`showWeekNumbers`	`boolean`	`false`	Render a leading row header with the ISO 8601 week number of each row.
`weekNumberLabel`	`string`	`"Wk"`	Visible week-number column header.
`weekNumberHeader`	`string`	`"Week"`	Full week-number column header used as `abbr`.

Slots

Slot	Slot props	Description
`weekday`	`CalendarWeekdaySlotState`	Weekday column header content. Receives the weekday, its labels, and column index.
`weekNumber`	`CalendarWeekNumberSlotState`	Week-number row header content. Receives the ISO week and the row's days.
`day`	`CalendarDayState`	Day button content. Receives the complete day state; defaults to the localized day number.

`DatePickerHeading`

Source: src/families/date-time/calendar/calendar-heading.vue

Slots

Slot	Slot props	Description
`default`	`CalendarHeadingSlotState`	Heading content. Receives the localized heading and visible months.

`DatePickerMonthSelect`

Source: src/families/date-time/calendar/calendar-month-select.vue

Props

Prop	Type	Default	Description
`ariaLabel`	`string`	`"Month"`	Accessible name of the native select.

Events

Event	Payload	Description
`change`	`[month: number, nativeEvent: Event]`	Fired after the user picks a month, with the ISO month number.

`DatePickerNext`

Source: src/families/date-time/calendar/calendar-next.vue

Props

Prop	Type	Default	Description
`unit`	`CalendarNavigationUnit`	`"month"`	Whether the control pages by month (or `numberOfMonths` when paged) or by year.
`ariaLabel`	`string`	`undefined`	Accessible name; defaults to "Next month" or "Next year".

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before navigation. Call `preventDefault()` to keep the view unchanged.

Slots

Slot	Slot props	Description
`default`	`CalendarNavigationSlotState`	Control content. Receives the unit and whether navigation is possible.

`DatePickerPrev`

Source: src/families/date-time/calendar/calendar-prev.vue

Props

Prop	Type	Default	Description
`unit`	`CalendarNavigationUnit`	`"month"`	Whether the control pages by month (or `numberOfMonths` when paged) or by year.
`ariaLabel`	`string`	`undefined`	Accessible name; defaults to "Previous month" or "Previous year".

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before navigation. Call `preventDefault()` to keep the view unchanged.

Slots

Slot	Slot props	Description
`default`	`CalendarNavigationSlotState`	Control content. Receives the unit and whether navigation is possible.

`DatePickerYearSelect`

Source: src/families/date-time/calendar/calendar-year-select.vue

Props

Prop	Type	Default	Description
`from`	`number`	`undefined`	First listed year; defaults to the `min` year or ten years before the view.
`to`	`number`	`undefined`	Last listed year; defaults to the `max` year or ten years after the view.
`ariaLabel`	`string`	`"Year"`	Accessible name of the native select.

Events

Event	Payload	Description
`change`	`[year: number, nativeEvent: Event]`	Fired after the user picks a year.

Behavior

Normative state x input -> outcome table for the DatePicker compound (@vizejs/ui/date-picker): date-picker-root.vue, date-picker-field.vue, date-picker-content.vue, and date-picker-calendar.vue, with DatePickerTrigger re-exporting PopoverTrigger. The root wraps PopoverRoot, so dismissal, focus containment, and positioning follow popover.behavior.md; field and calendar rules follow date-field.behavior.md and calendar.behavior.md. Every row is proven by the named test.

#	State	Input	Outcome	Proven by
P1	closed	trigger activation	the trigger (`aria-haspopup="dialog"`) opens the calendar dialog, emits `update:open` and `open-change`, and moves focus to the selected (or today) day	`renders a date field with a trigger that opens a calendar dialog focused on the value`
P2	open	day activation	the value commits (`update:modelValue`, `change`), the popover closes, focus returns to the trigger, and the field segments update	`selecting a day commits the value, closes the popover, and restores focus to the trigger`
P3	open	field typing / Escape	a value typed in the field scrolls the open calendar to it; Escape dismisses	`typing in the field moves the open calendar and keyboard Escape dismisses`
P4	`closeOnSelect=false` / read-only	day activation	the popover stays open; read-only pickers never change the value	`closeOnSelect=false keeps the popover open and read-only blocks value changes`
P5	disabled / imperative	render / expose	disabled pickers disable the trigger and field; `setOpen` and `setValue` are exposed; `min` reaches the calendar	`disabled pickers cannot open and expose imperative value and open control`
P6	SSR/hydration	closed and open requests	byte-identical markup in both states; an open picker hydrates silently	`renders byte-identical closed and open picker markup across SSR requests`, `hydrates an open picker without mismatches`

DatePickerContent forwards placement, initialFocus, ariaLabel, and ariaLabelledby; every other PopoverContent prop (for example portalDisabled or offset) falls through as an attribute. Root data: data-vize-ui="date-picker", data-state (open/closed), data-value, data-disabled, data-readonly. Pass today or now to the root for SSR-stable calendars.