Skip to content

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".

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)} />
<script>
import TimeField from "@invisible-ui/svelte/TimeField.svelte";
</script>

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>
PropTypeDefaultDescription
valuestring | nullnull
hourCycleHourCycle | undefinedundefined12 or 24 hours. Defaults to the locale's cycle.
withSecondsbooleanfalse
disabledbooleanfalse
invalidbooleanfalseDomain-level invalid state. Structural time errors are detected automatically.
errorstring | undefinedundefinedVisible, actionable error text supplied by the application.
labelstring | undefinedundefinedAccessible label for the whole field.
namestring | undefinedundefinedForm field name — the formatted time is submitted under it (via a hidden input).
onValueChange((value: string | null) => void) | undefinedundefinedCalled with the formatted value (or null while incomplete).
onValueCommit((value: string | null) => void) | undefinedundefinedCalled when the user finishes editing: focus leaves the field, or Enter.
minstring | undefinedundefinedEarliest acceptable time ("HH:mm[:ss]"), inclusive.
maxstring | undefinedundefinedLatest acceptable time ("HH:mm[:ss]"), inclusive.
onValidationChange((error: TimeValueError | null) => void) | undefinedundefinedCalled when structural validation changes; null means no structural error.
  • 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, so 0930 fills the hour and the minute.
  • hourCycle and withSeconds are construction-time configuration.
  • Without hourCycle, every adapter follows the locale’s hour cycle: the Locale Provider’s, else the page’s lang, else 24 hours, the international default (see Default locale).
<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-*.