Time Field

TimeField renders locale-ordered hour, minute, second, and day-period controls. It supports 12/24-hour cycles, keyboard editing, paste, constraints, Field state, and native forms.

Use Time Field for editable clock values. Style generated segments through ui, semantic classes, data attributes, and slots.

Anatomy

• #literal: Locale separator content, such as : or spacing.
• #day-period: AM/PM button content with canonical value, localized label, and toggle action.
• #time-zone: Time-zone label content for ZonedDateTime values.

Time Field generates the root group, segment container, spinbutton inputs, locale literals, optional day-period button, optional time-zone label, and native form input.

Usage

<script setup lang="ts">
import type { TimeValue } from "akaza-ui";
import { Time } from "@internationalized/date";
import { shallowRef } from "vue";
import { TimeField } from "akaza-ui";

const value = shallowRef<TimeValue>(new Time(9, 30));
</script>

<template>
  <TimeField v-model="value" :hour-cycle="12" />
</template>

Examples

12-hour and 24-hour cycles

Omit hourCycle to follow locale preference. Bind numeric 12 or 24 when product requirements must override it.

<TimeField v-model="time" :hour-cycle="12" />
<TimeField v-model="time" :hour-cycle="24" />

In 12-hour mode, day period is a real button. It works with click, touch, arrow keys, and direct A or P input.

Granularity

granularity renders through the requested smallest unit. Omitted minutes or seconds are stored as zero when a complete value is committed.

<TimeField v-model="hour" granularity="hour" />
<TimeField v-model="minute" granularity="minute" />
<TimeField v-model="precise" granularity="second" />

Step and snapping

Step values control keyboard increments for each segment. stepSnapping also rounds complete typed or pasted values to the nearest combined interval.

<TimeField
  v-model="time"
  :step="{ minute: 15 }"
  step-snapping
/>

Constraints and unavailable times

Constraints report native validity after interaction without turning an untouched field red.

<TimeField
  v-model="time"
  :min-value="new Time(9)"
  :max-value="new Time(17)"
  :is-time-unavailable="value => value.hour === 12"
/>

Field and native form

TimeField inherits id, name, required, disabled, descriptions, and validation presentation from Field.

<Field label="Meeting time" name="meeting" required>
  <TimeField v-model="time" />
</Field>

Complete values submit ISO time strings such as 09:30:00. Disabled controls are omitted from FormData.

Zoned values

Passing a ZonedDateTime preserves its date and zone when editing time fields. The zone identifier is visible unless hideTimeZone is enabled.

<TimeField v-model="zonedTime" />
<TimeField v-model="zonedTime" hide-time-zone />

Cancel changes

<TimeField
  v-model="time"
  @value-change="(value, details) => {
    if (value && value.hour < 8) details.cancel()
  }"
/>

Canceled updates restore segment text to the accepted model.

Reactive validation

Native validity tracks controlled values and reactive time constraints without an extra keystroke. Validation feedback remains interaction-driven. Native reset restores the initial time/segments and clears interaction state unless the reset event is canceled.

API Reference

Models

Props

Emits

Slots

Methods

UI Options

Styling Hooks

Direct class applies to root. Use ui.segment, ui.dayPeriod, and other keys for generated inner parts.

Keyboard

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