❯
◇

DatePicker

11 parts

A single-date picker that pairs a popover-anchored calendar with an optional trigger, field, and hidden form input. Owns the selected date, placeholder month, and open state, and provides both date-picker and calendar context to its parts. Use it when you need a compact, accessible "pick one date" control (e.g. a form field) rather than an always-visible Calendar.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue
import {
  DatePickerRoot,
  DatePickerTrigger,
  DatePickerAnchor,
  DatePickerPortal,
  DatePickerContent,
  DatePickerArrow,
  DatePickerClose,
  DatePickerCalendar,
  DatePickerField,
  DatePickerFieldRoot,
  DatePickerFieldSegment,
} from '@robonen/primitives/display/date-picker';

<DatePickerRoot>
  <DatePickerTrigger />
  <DatePickerAnchor />
  <DatePickerPortal />
  <DatePickerContent />
  <DatePickerArrow />
  <DatePickerClose />
  <DatePickerCalendar />
  <DatePickerField />
  <DatePickerFieldRoot />
  <DatePickerFieldSegment />
</DatePickerRoot>

API Reference

DatePickerRoot

Root

A single-date picker that pairs a popover-anchored calendar with an optional trigger, field, and hidden form input. Owns the selected date, placeholder month, and open state, and provides both date-picker and calendar context to its parts. Use it when you need a compact, accessible "pick one date" control (e.g. a form field) rather than an always-visible `Calendar`.

PropTypeDescription
defaultOpen?booleanUncontrolled initial open state.
modal?booleanModal popover (traps focus + blocks outside pointer).
name?stringHidden form input name for submission.
id?stringId forwarded to the focusable form control / first segment.
required?booleanMarks the form control as required for native constraint validation.
valueFormat?'iso' | ((d: Date) => string)Format used to serialize the hidden input value.
closeOnSelect?booleanClose popover on selection.
preventDeselect?booleanKeep the current value selected when the already-selected date is picked again (otherwise re-selecting clears it).
granularity?GranularitySmallest unit the field edits. 'day' is date-only; 'hour'/'minute'/ 'second' add time segments and preserve the time-of-day.
hourCycle?HourCycleHour cycle for the time segments (12 or 24). Inferred from locale if omitted.
open?booleanTwo-way bound value (v-model:open).
modelValue?Date | undefinedTwo-way bound value (v-model).
placeholder?DateTwo-way bound value (v-model:placeholder).
Emits
EventPayload
update:open[value: boolean]
update:modelValue[value: Date | undefined]
update:placeholder[value: Date]

DatePickerTrigger

Trigger

The button that toggles the picker popover open and closed. Acts as the Popper anchor (unless a custom `DatePickerAnchor` is present) and carries the dialog-related ARIA wiring (`aria-haspopup`, `aria-expanded`, `aria-controls`).

No props or events — renders its element and forwards attributes.

DatePickerAnchor

Anchor

Optional custom anchor for positioning the popover against an element other than the trigger (e.g. a field or input group). When present, the trigger stops acting as the anchor and the content is positioned relative to this.

No props or events — renders its element and forwards attributes.

DatePickerPortal

Portal

Teleports the popover content into a different part of the DOM (the body by default) so it escapes overflow/stacking-context clipping. Wrap `DatePickerContent` with it when the picker lives inside a scrolled or transformed container.

No props or events — renders its element and forwards attributes.

DatePickerContent

Content

The popover panel that holds the calendar. Handles Popper positioning, presence (mount/unmount on open), focus trapping/restoration, and dismissal via Escape or outside interaction. Renders only while open unless `forceMount` is set.

PropTypeDescription
forceMount?booleanKeep mounted for CSS exit animations.

DatePickerArrow

Arrow

An optional arrow rendered inside `DatePickerContent` that points back at the trigger/anchor. Purely decorative; place it as a child of the content.

No props or events — renders its element and forwards attributes.

DatePickerClose

Close

A button that closes the picker popover when clicked. Render it inside `DatePickerContent` (e.g. a "Done" or dismiss action).

No props or events — renders its element and forwards attributes.

DatePickerCalendar

Calendar

A styling wrapper for the calendar grid rendered inside the popover. The calendar subparts (`DatePickerGrid`, `DatePickerCell`, etc.) consume the calendar context provided by `DatePickerRoot`; this element just groups and labels them with a `data-primitives-date-picker-calendar` hook.

No props or events — renders its element and forwards attributes.

DatePickerField

Field

A text input that renders the selected date and, when `editable`, lets users type a date that is parsed and committed back to the picker on blur/Enter. Aliased as `DatePickerInput`; defaults to a read-only display of the value.

PropTypeDescription
editable?booleanAllow typing into the field.
format?Intl.DateTimeFormatOptionsDisplay format for the rendered value.
placeholderText?stringPlaceholder text shown when no value is selected.

DatePickerFieldRoot

FieldRoot

A segmented date field: a `role="group"` of individually-focusable `role="spinbutton"` segments (`DatePickerFieldSegment`) that edit one part of the date each. It reads the picker's value, placeholder, locale, granularity, and hour cycle from `DatePickerRoot`, and commits a complete date back to the picker. This is the accessible, keyboard-driven alternative to the plain `DatePickerField` text input. The default slot receives the ordered `segments` descriptors (including literals) and the current `modelValue`, so the consumer renders a `DatePickerFieldSegment` per segment.

No props or events — renders its element and forwards attributes.

DatePickerFieldSegment

FieldSegment

A single segment of a `DatePickerFieldRoot`. Editable parts (`day`, `month`, `year`, `hour`, `minute`, `second`, `dayPeriod`) render as a focusable `role="spinbutton"` with `aria-valuemin/max/now/valuetext`; `literal` parts render as inert separators. Supports arrow increment/decrement, numeric type-ahead with auto-advance, Backspace to clear, and `a`/`p` for AM/PM.

PropTypeDescription
partSegmentPartThe date part this segment edits.