Date Range Field

DateRangeField combines two segmented date inputs under one range model. It supports locale order, partial entry, range constraints, Field state, cancelable changes, and two native form values.

Use Date Range Field for typed start and end dates. Date Range Picker adds calendar selection.

Anatomy

• root: Generated range group containing both endpoint fields.
• start: Generated start-endpoint wrapper.
• start field: Generated Date Field for the start value.
• #start-literal: Replaces locale separators inside the start field.
• #separator: Replaces the visual separator between endpoints.
• end: Generated end-endpoint wrapper.
• end field: Generated Date Field for the end value.
• #end-literal: Replaces locale separators inside the end field.
• hidden input: Generated aggregate validity control. Each endpoint Date Field also owns its ISO form input.

Date Range Field owns endpoint segment markup because focus movement, spinbutton values, partial text, labels, and validation must stay synchronized. Every visible generated part remains styleable through ui.

Usage

<script setup lang="ts">
import type { CalendarDateRange } from "akaza-ui";
import { CalendarDate } from "@internationalized/date";
import { DateRangeField } from "akaza-ui";
import { shallowRef } from "vue";

const range = shallowRef<CalendarDateRange>({
  start: new CalendarDate(2026, 8, 12),
  end: new CalendarDate(2026, 8, 18),
});
</script>

<template>
  <DateRangeField v-model="range" />
</template>

Examples

Field integration

Wrap Date Range Field in Field to inherit label, description, required, disabled, name, and error relationships. Aggregate validation stays quiet until users interact or submit.

<Field
  label="Travel dates"
  name="travel"
  description="Choose arrival and departure."
  required
>
  <DateRangeField v-model="range" />
</Field>

The default form names become travel.start and travel.end. Use startName and endName to override either name.

Range constraints

Boundaries apply to both endpoints. maximumDays counts both start and end. Unavailable dates inside a range invalidate it unless non-contiguous ranges are allowed.

<DateRangeField
  v-model="range"
  :min-value="new CalendarDate(2026, 8, 1)"
  :max-value="new CalendarDate(2026, 9, 30)"
  :maximum-days="14"
  :is-date-unavailable="(date) => closedDates.has(date.toString())"
/>

Set allowNonContiguousRanges when unavailable interior dates may be skipped conceptually. Start and end must still be available.

Fixed endpoint

Keep one known boundary read-only while users edit the other. The fixed endpoint is exposed through data-akaza-fixed-date.

<DateRangeField v-model="range" fixed-date="start" />

Locale order and paste

Both endpoints use the same locale. For en-GB, visual and focus order is day, month, year. Paste a date with three numeric groups into either endpoint.

<DateRangeField v-model="range" locale="en-GB" />

Cancel changes

Endpoint edits emit the complete proposed range before the model changes. Reasons are prefixed with start- or end-.

<DateRangeField
  v-model="range"
  @value-change="(next, details) => {
    if (next.end?.day === 20) details.cancel()
  }"
/>

Read-only and disabled

Read-only segments stay focusable for inspection. Disabled segments leave the tab sequence and both endpoint values are excluded from form submission.

<DateRangeField :model-value="range" read-only />
<DateRangeField :model-value="range" disabled />

Reactive validation

Controlled value and constraint changes update native validity. Partial endpoints count toward range validity. A canceled form reset keeps both drafts.

API Reference

Model

Props

Emits

Slots

Methods

UI Options

Styling Hooks

Nested endpoint parts retain Date Field's exact semantic classes and data attributes. Plain class applies to the Date Range Field root; use ui.startField and ui.endField for generated segment internals.

Keyboard

Each endpoint follows Date Field keyboard behavior. Tab moves through start segments, then end segments. Root uses role="group"; each date segment remains a labeled role="spinbutton".