Time Field
A segmented time input — hour : minute, optional seconds, 12- or 24-hour with an
AM/PM segment. Each segment is a role="spinbutton".
Value, commit and bounds
Section titled “Value, commit and bounds”The value is the canonical 24-hour string (HH:mm[:ss]) and it is published
only once every required segment is filled — a half-typed hour is not a time.
onValueChange follows the segments as they fill; onValueCommit fires when
the user finishes: focus leaves the whole field (moving between segments is
ordinary editing), or Enter is pressed. Enter never blocks form submission.
Escape puts the segments back to the last finished value, and passes the key
on when there is nothing to undo, so a Time Field inside a dialog does not
swallow it.
min and max are reported, not enforced: the arrows keep wrapping (23 → 00)
and an out-of-range time is announced as invalid with the bound in the message.
Nothing is silently corrected.
<TimeField label="Start" value="08:30" min="09:00" max="17:00" onValueCommit={(v) => check(v)} />Import
Section titled “Import”<script> import TimeField from "@invisible-ui/svelte/TimeField.svelte";</script><script setup> import { TimeField } from "@invisible-ui/vue";</script>import { TimeField } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-time-field></ds-time-field>In Elements, the hour cycle follows the locale unless hour-cycle is set, and name submits the time with the form:
<form> <ds-time-field label="Start" name="start" value="08:30" min="09:00"></ds-time-field></form>| Prop | Type | Default | Description |
|---|---|---|---|
value | string | null | null | |
hourCycle | HourCycle | undefined | undefined | 12 or 24 hours. Defaults to the locale's cycle. |
withSeconds | boolean | false | |
disabled | boolean | false | |
invalid | boolean | false | Domain-level invalid state. Structural time errors are detected automatically. |
error | string | undefined | undefined | Visible, actionable error text supplied by the application. |
label | string | undefined | undefined | Accessible label for the whole field. |
name | string | undefined | undefined | Form field name — the formatted time is submitted under it (via a hidden input). |
onValueChange | ((value: string | null) => void) | undefined | undefined | Called with the formatted value (or null while incomplete). |
onValueCommit | ((value: string | null) => void) | undefined | undefined | Called when the user finishes editing: focus leaves the field, or Enter. |
min | string | undefined | undefined | Earliest acceptable time ("HH:mm[:ss]"), inclusive. |
max | string | undefined | undefined | Latest acceptable time ("HH:mm[:ss]"), inclusive. |
onValidationChange | ((error: TimeValueError | null) => void) | undefined | undefined | Called when structural validation changes; null means no structural error. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | null | undefined | Value as "HH:mm" or "HH:mm:ss" (24h); bindable with v-model. |
value | string | null | null | |
hourCycle | HourCycle | undefined | 12 or 24 hours. Defaults to the locale's cycle. |
withSeconds | boolean | false | |
disabled | boolean | false | |
invalid | boolean | false | Domain-level invalid state. Structural time errors are detected automatically. |
error | string | undefined | Visible, actionable error text supplied by the application. |
label | string | undefined | Accessible name for the whole field. Defaults to the catalog's "Time". |
name | string | undefined | Form field name; the formatted time is submitted under it. |
onValueChange | (value: string | null) => void | undefined | |
onValidationChange | (error: TimeValueError | null) => void | undefined | Called when structural validation changes; null means no structural error. |
onValueCommit | (value: string | null) => void | undefined | Called when the user finishes editing: focus leaves the field, or Enter. |
min | string | undefined | Earliest acceptable time ("HH:mm[:ss]"), inclusive. |
max | string | undefined | Latest acceptable time ("HH:mm[:ss]"), inclusive. |
| Event | Payload |
|---|---|
update:modelValue | value: string | null |
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | null | null | Initial (uncontrolled) or current (controlled) value, HH:mm[:ss] (24h), or null. |
hourCycle | HourCycle | — | 12 or 24 hours. Defaults to the provider locale's preference. |
withSeconds | boolean | false | Include a seconds segment. |
disabled | boolean | false | |
invalid | boolean | false | Domain-level invalid state. Structural time errors are detected automatically. |
error | string | — | Visible, actionable error text supplied by the application. |
label | string | — | Accessible label for the whole field. Defaults to the catalog's. |
name | string | — | Form field name; the canonical time (HH:mm[:ss]) is submitted under it. |
form | string | — | Id of the owning form when the field renders outside of it. |
min | string | — | Earliest acceptable time (HH:mm[:ss]), inclusive. Reported, never enforced. |
max | string | — | Latest acceptable time (HH:mm[:ss]), inclusive. Reported, never enforced. |
onValueChange | (value: string | null) => void | — | Called with the canonical value when every required segment is filled, else null. |
onValueCommit | (value: string | null) => void | — | Called when the user finishes editing: focus leaves the field, or Enter. |
onValidationChange | (error: TimeValueError | null) => void | — | Called when an edit changes the structural error; null means none. |
| Attribute | Reactive | Description |
|---|---|---|
value | yes | HH:mm[:ss] |
name | yes | |
hour-cycle | yes | 12|24 |
with-seconds | yes | |
min | yes | |
max | yes | |
label | yes | |
error | yes | visible error text |
invalid | yes | |
disabled | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: value, validationError (read only).
Emits: change (detail.value) on every value change, commit (detail.value) when editing ends (focus leaves the field, or Enter), and validation-change (detail.error) when an edit changes the value's own error. A value set from outside, or put back by a form reset, updates validationError without an event (ADR 0011, ADR 0012). Inside a disabled <fieldset> the field is disabled too.
Accessibility
Section titled “Accessibility”- Each segment is a
role="spinbutton": ArrowUp/Down increment/decrement (wrapping), Left/Right move between segments, digits type with auto-advance, Backspace clears, and A/P set the period in 12-hour mode. - Arabic-Indic (٠–٩) and Persian (۰–۹) digits type as 0–9 in every locale,
from a hardware or a soft keyboard. The value stays the ASCII
HH:mm[:ss]. - Pasting a whole time, such as
09:30, sets every segment; other pasted text types its characters from the focused segment, as the keys would, so0930fills the hour and the minute. hourCycleandwithSecondsare construction-time configuration.- Without
hourCycle, every adapter follows the locale’s hour cycle: the Locale Provider’s, else the page’slang, else 24 hours, the international default (see Default locale).
Example
Section titled “Example”<TimeField value="09:30" label="Start time" /><TimeField value="14:05:30" hourCycle={12} withSeconds label="Meeting time" />In React, the hour cycle follows the provider’s locale unless hourCycle is
set, and onValueCommit reports the time when editing ends:
<TimeField label="Start" value={start} min="09:00" name="start" onValueCommit={setStart} />Themeable via --ds-time-field-*.