Time Field

STimeField is a segmented time input: separate editable parts (hours, minutes, and seconds and AM/PM when needed). It works from the keyboard (arrow keys increment), is localized and respects the 12/24-hour format. The value is a Time (or CalendarDateTime/ZonedDateTime) from @internationalized/date; it is built on SFormField. The time counterpart of SDateField. Keep the value in a shallowRef, not a ref: a regular ref unwraps the date class, and type checking no longer recognizes it as a DateValue.

Basic usage

<script setup>
import { shallowRef } from 'vue'
import { parseTime } from '@internationalized/date'
const time = shallowRef(parseTime('14:30'))
</script>

<template>
  <STimeField
    v-model="time"
    label="Appointment time"
  />
</template>

12-hour format and seconds

<template>
  <STimeField
    label="12-hour format"
    :hour-cycle="12"
    locale="en-US"
  />
  <STimeField
    label="With seconds"
    granularity="second"
  />
</template>

Hint and error

hint shows helper text below the field, error shows an error message and marks the field invalid.

<template>
  <STimeField
    v-model="time"
    label="Start"
    hint="24-hour format"
    :hour-cycle="24"
  />
  <STimeField
    label="Start"
    error="Enter a time"
  />
</template>

States

disabled blocks the field, readonly prevents changing the segments, invalid marks the field invalid (red border), required adds * to the label.

<template>
  <STimeField
    v-model="time"
    label="Disabled"
    disabled
  />
  <STimeField
    v-model="time"
    label="Read-only"
    readonly
  />
  <STimeField
    v-model="time"
    label="Invalid"
    invalid
  />
  <STimeField
    v-model="empty"
    label="Required"
    required
  />
</template>

Sizes

The size prop controls the field height: sm (28px), md (36px, default) and lg (44px).

<template>
  <STimeField
    v-model="time"
    label="sm"
    size="sm"
  />
  <STimeField
    v-model="time"
    label="md"
    size="md"
  />
  <STimeField
    v-model="time"
    label="lg"
    size="lg"
  />
</template>

prepend / append slots

The prepend and append slots put content inside the field border — for example, a clock icon.

<template>
  <STimeField
    v-model="time"
    label="Leading icon"
  >
    <template #prepend>
      <SIcon
        icon="clock"
        :size="16"
      />
    </template>
  </STimeField>

  <STimeField
    v-model="time"
    label="Trailing icon"
  >
    <template #append>
      <SIcon
        icon="clock"
        :size="16"
      />
    </template>
  </STimeField>
</template>

Leaving the field

The field has focus and blur events, like SInput. Moving between segments does not count as leaving — see the details and a validation example on the SDatePicker page.

API

Props

Name	Type	Default	Description
id	string	undefined	Field id. Generated automatically when not set (SSR-safe).
label	string	undefined	Field label.
floating-label	boolean	true	Floating label: the label sits inside the border, looks like a placeholder at rest and floats up to the top edge on focus or when filled. On by default; false renders a regular label above the field. The label size is fixed and does not depend on size.
hint	string	undefined	Hint below the field.
error	string	undefined	Error message. When set, the field is marked invalid.
size	"md" | "sm" | "lg"	"md"	Field size: sm (32px), md (40px) or lg (48px).
disabled	boolean	false	Disables input and makes the field inactive.
readonly	boolean	false	Read-only: the segments cannot be changed.
required	boolean	false	Marks the field as required: adds * to the label.
invalid	boolean	false	Explicitly marks the field invalid (in addition to error).
square	boolean	undefined	Square corners: removes the field border radius (rounded by default).
locale	string	undefined	Formatting locale (for example en-GB). Derived from the library locale by default (ConfigProvider/installLocale, in Nuxt the locale option): en → en-US.
hour-cycle	12 | 24	undefined	Hour cycle: 12- or 24-hour. Defaults to the locale's preference.
granularity	"hour" | "minute" | "second"	undefined	Granularity: the smallest segment to display (hour/minute/second).
min-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Minimum allowed time.
max-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Maximum allowed time.
model-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Time value (Time/CalendarDateTime/ZonedDateTime). Two-way bound via v-model.

Events

Name	Signature	Description
update:modelValue	( value: | Time | CalendarDateTime | ZonedDateTime | undefined ) => void	Emitted when modelValue changes. Used for two-way binding (v-model).
focus	(event: FocusEvent) => void	Focus entered the field. Moving between segments does not count.
blur	(event: FocusEvent) => void	Focus left the field. Moving between segments does not count.

Slots

Name	Description
prepend	Content at the start of the field, inside the border (icon, button).
append	Content at the end of the field, inside the border (icon, button).