Date Time Field

Accessible, unstyled segmented date-and-time input in locale order with 12/24-hour clocks.


Package	`@vizejs/ui/datetime-field`
Maturity	stable
Own the source	`vize lib pull datetime-field`
Requires	calendar, controllable-state, date-field, id, locale, time-field
Aliases	datetime input, datetime-local, appointment time, timestamp field
Covers	HTML input type=datetime-local, React Aria DatePicker granularity, WAI-ARIA spinbutton

Usage

import { DateTimeField } from "@vizejs/ui/datetime-field";

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

API

`DateTimeField`

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

Props

Prop	Type	Default	Description
`id`	`string \| null \| undefined`	`undefined`	Consumer-owned group id; nullish values use a deterministic fallback.
`name`	`string \| undefined`	`undefined`	Hidden input name that submits `YYYY-MM-DDTHH:MM[:SS]` with forms.
`modelValue`	`PlainDateTime \| null \| undefined`	`undefined`	Controlled date-time; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`PlainDateTime \| null \| undefined`	`null`	Initial uncontrolled date-time and native form-reset target.
`min`	`PlainDateTime \| null \| undefined`	`undefined`	Earliest valid date-time; earlier values mark the field invalid.
`max`	`PlainDateTime \| null \| undefined`	`undefined`	Latest valid date-time; later values mark the field invalid.
`isDateUnavailable`	`DateMatcher \| undefined`	`undefined`	Predicate for dates that are entered but invalid.
`timeZone`	`string \| undefined`	`undefined`	IANA time zone for the key-time host clock fallback.
`hourCycle`	`HourCycle \| undefined`	`undefined`	`12` shows 1–12 plus an AM/PM segment, `24` shows 0–23; defaults to the locale clock.
`granularity`	`TimeGranularity \| undefined`	`"minute"`	Smallest edited unit; `second` adds a seconds segment.
`placeholderValue`	`PlainDateTime \| null \| undefined`	`undefined`	Date-time whose segments seed stepping from empty; defaults to the host clock at key time.
`locale`	`string \| undefined`	`undefined`	BCP 47 locale deciding segment order, clock, and labels; defaults to the nearest LocaleProvider.
`dir`	`"ltr" \| "rtl" \| undefined`	`undefined`	Text direction for arrow-key segment movement; defaults to the nearest LocaleProvider.
`disabled`	`boolean \| undefined`	`false`	Remove every segment from focus and editing.
`readOnly`	`boolean \| undefined`	`false`	Keep segments focusable while blocking edits.
`required`	`boolean \| undefined`	`false`	Require a complete value; participates in native form validation.
`invalidMessage`	`string \| undefined`	`"Invalid value"`	Custom validity message reported while the value is out of range or unavailable.
`placeholders`	`FieldSegmentPlaceholders \| undefined`	`{ hour: "––", minute: "––", second: "––", dayPeriod: "––" }`	Placeholder text for empty segments.
`emptyText`	`string \| undefined`	`"Empty"`	Text announced for empty segments.
`ariaLabel`	`string \| undefined`	`undefined`	Accessible name for the segment group.
`ariaLabelledby`	`string \| undefined`	`undefined`	Ids that label the segment group.
`ariaDescribedby`	`string \| undefined`	`undefined`	Ids that describe the group and every segment.
`ariaErrormessage`	`string \| undefined`	`undefined`	Id of the validation message used while invalid.
`ariaInvalid`	`boolean \| undefined`	`false`	Force the invalid state in addition to built-in min/max validation.

Events

Event	Payload	Description
`update:modelValue`	`[value: PlainDateTime \| null]`	Fired when segments request a new controlled date-time or `null` while incomplete.
`change`	`[value: PlainDateTime \| null, previous: PlainDateTime \| null, nativeEvent: Event \| null]`	Fired after a distinct committed date-time with the previous date-time and triggering event.

Slots

Slot	Slot props	Description
`default`	`DateTimeFieldSlotState`	Extra content after the segments, such as a picker trigger. Receives field state.
`segment`	`FieldSegmentState`	Segment content. Receives the segment state; defaults to its text.

Behavior

Normative state x input -> outcome table for datetime-field.vue (@vizejs/ui/datetime-field). DateTimeField renders date and time segments in one locale order on the shared segment engine, so DateField rows F2–F8, F10–F12, and F15 and TimeField rows T2–T4 apply. Every row below is proven by the named test.

#	State	Input	Outcome	Proven by
DT1	locale	render	year/month/day and hour/minute(/second)/day-period segments follow `Intl` order for the locale and clock; `name` submits `YYYY-MM-DDTHH:MM[:SS]`	`renders date and time segments in one locale order with a named ISO input`
DT2	empty	digits	typing advances across the date/time boundary and commits one `PlainDateTime` only when every segment is filled	`typing fills every segment and commits a PlainDateTime`
DT3	min / max / dates	commit / empty step	out-of-window date-times or unavailable dates are invalid; empty segments step from `placeholderValue` (else the host clock at key time)	`min, max, and unavailable dates invalidate; placeholderValue seeds stepping`
DT4	imperative	expose	`setValue`, `clear`, and 12-hour rendering of midnight	`exposes the date-time value and imperative editing`
DT5	model	helpers	`PlainDateTime` compare, minute arithmetic across days, ISO parsing, and zoned-instant resolution	`plain date-time helpers compare, shift, parse, and resolve zoned instants`
DT6	SSR/hydration	isolated requests	byte-identical segments and deterministic ids hydrate silently	`renders byte-identical locale-ordered date-time segments across SSR requests`, `hydrates date-time segments with generated ids and no mismatches`

Root data: data-vize-ui="datetime-field", data-state, data-value, data-hour-cycle, data-granularity; parts root, segment, literal.