Skip to content

Time Field

Enter a time with separate editable segments.

Demos

Size
Variant

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Installation

Complete the shared installation. Copy TimeField.vue and index.ts into app/components/ui/time-field/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm
variantoutline, soft, bareoutline

Models

ModelTypeDefaultDescription
v-modelTimeValue | undefinedundefinedAccepted clock value. Existing date and zone data are preserved.
v-model:placeholderTimeValue | undefinedplaceholder or midnightBase value used before a model exists; accepted edits update it.

Props

PropTypeDefaultDescription
idstringField id or generatedId placed on first segment.
namestringField nameNative form name.
localestring"en-US"Segment order, literals, labels, and default hour cycle.
dir"ltr" | "rtl""ltr"Reading direction and horizontal focus movement.
placeholderTimeValuemidnightBase time and value type used before selection.
minValueTimeValue—Earliest valid clock time.
maxValueTimeValue—Latest valid clock time.
isTimeUnavailable(time) => boolean—Application-level unavailable matcher.
granularity"hour" | "minute" | "second""minute"Smallest rendered and committed unit.
hourCycle12 | 24locale preferenceExplicit hour cycle. Use :hour-cycle="24", not a string attribute.
hideTimeZonebooleanfalseHides zone label for zoned values.
step{ hour?, minute?, second? }each segment 1Segment stepping and optional snap interval.
stepSnappingbooleanfalseRounds complete values to nearest combined step.
requiredbooleanfalseRequires a complete time.
disabledbooleanfalseDisables all segments and native submission.
readOnlybooleanfalseAllows focus but blocks edits.
invalidbooleanfalseForces invalid presentation.
selectOnFocusbooleantrueSelects segment text on focus.
autoAdvancebooleantrueMoves focus after two digits.
ariaLabelstring"Time"Root label when no labelled-by relation exists.
ariaLabelledbystringField label idExplicit label relation.
ariaDescribedbystringField description/error idsExplicit description relation.
uiTimeFieldUi—Classes for generated parts.

Slots

SlotPropsDescription
literalvalueLocale separator content.
day-periodvalue, label, toggleAM/PM control content and event-safe toggle action.
time-zonevalueZone identifier content.

Events

EventPayloadDescription
update:modelValueTimeValue | undefinedFires after accepted value changes.
update:placeholderTimeValue | undefinedFires when accepted interaction updates placeholder.
value-change(value, details)Fires before model mutation. details.cancel() rejects it.
value-commit(value, details)Fires after complete input, keyboard, paste, day-period, blur, or clear commit.

Keyboard

KeyBehavior
Number keysReplaces selected segment text. Complete segments update model.
ArrowUp / ArrowDownSteps focused segment, wrapping at boundaries.
PageUp / PageDownSteps focused segment by ten increments.
Home / EndSets segment minimum or maximum.
ArrowLeft / ArrowRightMoves between segments and day period, reversed in RTL.
BackspaceClears text; when empty, moves to previous segment.
A / PSets AM or PM while day period is focused.
PasteDistributes colon- or space-separated time parts.

Each numeric segment uses role="spinbutton" with value bounds. Native inputs and button semantics provide keyboard, mouse, touch, and screen-reader behavior.