Time Range Field

TimeRangeField combines two Time Field controls under one range model and validity state. It supports locale order, granularity, constraints, partial input, Field integration, and separate form values.

The end time must be equal to or later than the start time.

Anatomy

• #start-literal: Locale separators inside start field.
• #start-day-period: Start AM/PM content and action.
• #start-time-zone: Start zone content.
• #separator: Decorative separator between endpoints.
• #end-literal: Locale separators inside end field.
• #end-day-period: End AM/PM content and action.
• #end-time-zone: End zone content.

The root generates endpoint wrappers, two functional Time Fields, separator, and aggregate native validity input.

Usage

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

const value = shallowRef<TimeRange>({
  start: new Time(9),
  end: new Time(17),
});
</script>

<template>
  <TimeRangeField v-model="value" :hour-cycle="24" />
</template>

Examples

Required range with Field

Aggregate validation starts after interaction. Untouched empty fields remain neutral; blur or submit reveals missing endpoints and Field error text.

<Field label="Availability" name="window" required>
  <TimeRangeField v-model="range" />
</Field>

FormData receives window.start and window.end. Set startName and endName when a backend expects different keys.

Constraints

<TimeRangeField
  v-model="range"
  :min-value="new Time(8)"
  :max-value="new Time(20)"
  :is-time-unavailable="isUnavailable"
/>

Each endpoint validates boundaries and unavailable values. The parent additionally rejects reversed ranges.

Seconds and step

<TimeRangeField
  v-model="range"
  granularity="second"
  :step="{ minute: 15 }"
  step-snapping
/>

Custom endpoint presentation

Use nested startField and endField UI objects for segment parts while root UI keys style range layout.

<TimeRangeField
  :ui="{
    root: 'flex rounded border',
    startField: { segment: 'tabular-nums' },
    separator: 'text-neutral-500',
    endField: { segment: 'tabular-nums' },
  }"
/>

Cancel changes

value-change reports the proposed full range with reasons such as start-input and end-keyboard.

<TimeRangeField
  v-model="range"
  @value-change="(value, details) => {
    if (isLocked(value)) details.cancel()
  }"
/>

Reactive validation

Aggregate range validity includes partial endpoint drafts and reacts to changing min/max and other constraints. Child styling attributes are not the source of validation state. Native reset restores both initial endpoints unless canceled.

API Reference

Models

Props

Emits

Slots

Methods

UI Options

Styling Hooks

Keyboard

Each endpoint uses Time Field keyboard behavior:

Mouse and touch edit the native inputs and day-period buttons. The component does not require hover input.