Time Picker

STimePicker is a time field with a panel: the segmented input of STimeField plus a button that opens columns of hours, minutes, seconds and AM/PM to pick from. It is the time counterpart of SDatePicker — use STimeField when typing is enough, and STimePicker when the value should also be pickable from a list. The value is a Time (or CalendarDateTime/ZonedDateTime) from @internationalized/date; keep it in a shallowRef, not a ref. Picking from the panel keeps the class the value already had: a Time stays a Time, and a date-time keeps its date.

Every field prop of STimeField is forwarded (label, hint, error, size, disabled, readonly, required, invalid, square, locale, rules, validate-on), and the field still accepts typing into the segments.

Keyboard and accessibility. The trigger button carries aria-expanded and aria-haspopup; opening it moves focus to the hour column. Each column is a listbox of options named after its unit in the field's locale, and the current value is marked aria-selected and scrolled into view. ↑/↓ move inside a column, Home/End jump to its first and last entry, ←/→ cross to the neighbouring column, Enter or Space picks, and Esc closes the panel and returns focus to the field. Entries outside min-value/max-value are disabled and skipped by the arrows.

Basic usage

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

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

12-hour cycle

hour-cycle fixes the clock the field and the panel use. Left out, it follows the locale: a 12-hour locale gets an AM/PM column, a 24-hour one lists the hours from 00 to 23.

<template>
  <STimePicker
    label="12-hour cycle"
    :hour-cycle="12"
    locale="en-US"
  />
  <STimePicker
    label="24-hour cycle"
    :hour-cycle="24"
    locale="en-GB"
  />
</template>

Step and granularity

minute-step and second-step thin out the entries the panel offers; granularity decides how far the value goes and therefore which columns are drawn — hour leaves the hours alone, second adds a seconds column.

<template>
  <STimePicker
    v-model="shift"
    label="Every 15 minutes"
    :minute-step="15"
  />
  <STimePicker
    v-model="withSeconds"
    label="With seconds"
    granularity="second"
    :second-step="10"
  />
  <STimePicker
    label="Whole hours"
    granularity="hour"
  />
</template>

Allowed range

min-value and max-value disable the entries outside the range and mark a typed time outside it invalid. The minutes are read against the hour that is already picked, so they open up once the hour is inside the range.

<script setup>
import { shallowRef } from 'vue'
import { Time } from '@internationalized/date'
const delivery = shallowRef()
</script>

<template>
  <STimePicker
    v-model="delivery"
    label="Delivery window"
    hint="Between 09:30 and 17:00"
    :min-value="new Time(9, 30)"
    :max-value="new Time(17, 0)"
    :minute-step="10"
  />
</template>

Validation

rules run when focus leaves the field; picking from the panel does not count as leaving it. The rules receive the v-model value, a time or undefined while the field is empty: required() fails on it, and your own rules should let it pass (!v || …). SForm collects the field, blocks a submission that fails and focuses the first segment of the first invalid field. See the Validation guide for the details.

<script setup>
import { shallowRef } from 'vue'
import { required } from '@smalt-ui/core'
const booking = shallowRef()
</script>

<template>
  <SForm @submit="onSubmit">
    <STimePicker
      v-model="booking"
      label="Booking time"
      name="booking"
      :minute-step="30"
      :rules="[required()]"
    />
    <SButton type="submit"> Book </SButton>
  </SForm>
</template>

States and shape

disabled blocks the field and the button, readonly keeps the value as it is and does not open the panel, square removes the rounding of both the field and the panel, and flat/elevation control the shadow of the panel.

<template>
  <STimePicker
    v-model="appointment"
    label="Disabled"
    disabled
  />
  <STimePicker
    v-model="appointment"
    label="Read-only"
    readonly
  />
  <STimePicker
    v-model="appointment"
    label="Square"
    square
  />
  <STimePicker
    v-model="appointment"
    label="Flat panel"
    flat
  />
</template>

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 the field and the panel.
readonly	boolean	false	Read-only: neither the segments nor the panel can change the value.
name	string	undefined	Field name in native form submission: the value is sent in a hidden input.
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 rounding of the field and of the panel (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. Follows the locale by default, which also decides whether the panel shows an AM/PM column.
granularity	"hour" | "minute" | "second"	"minute"	Granularity: the smallest part the value has, which is also the last column of the panel.
minute-step	number	1	Step between the minutes offered by the panel.
second-step	number	1	Step between the seconds offered by the panel.
min-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Minimum allowed time; earlier entries in the panel are disabled.
max-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Maximum allowed time; later entries in the panel are disabled.
open-label	string	undefined	Accessible name of the button that opens the panel (defaults to the locale dictionary).
flat	boolean	undefined	Removes the shadow. Overridden by the elevation prop when it is set.
elevation	0 | 3 | 1 | 2 | 4 | 5	undefined	Shadow level 0–5 (scale); 0 means no shadow. Overrides flat.
rules	readonly	undefined	Validation rules: functions of the value that return true or the error text, run in order until the first failure. See Validation.
validate-on	"blur" | "input" | "submit"	undefined	When the field checks its rules: blur (after the user leaves the field, then on every change while an error is shown), input (on every change) or submit (only on form submission and validate()). Overrides validate-on of SForm; blur by default.
model-value	| CalendarDateTime | ZonedDateTime | Time	undefined	Selected time (Time, CalendarDateTime or 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).