Date Field

DateField splits a date into day, month, and year spinbutton segments. It supports locale order, keyboard stepping, validation, ISO paste, native form submission, and an optional Calendar.

Use Date Field for exact date entry. Set showCalendar to add visual date selection.

Anatomy

• root: Generated date group containing segments and optional calendar trigger.
• segments: Generated locale-ordered segment wrapper.
• segment: Generated day, month, or year text input with role="spinbutton".
• #literal: Optional replacement content for generated separators such as / or ..
• #calendar-trigger: Optional trigger content with open, close, and toggle actions.
• calendar content: Generated, positioned role="dialog" containing Calendar when showCalendar is enabled.
• #calendar: Replaces the built-in Calendar while retaining popup positioning and dismissal.
• hidden input: Generated native form control carrying the ISO date string and validity.

Date Field generates segment markup to coordinate editing, focus, labels, and spinbutton values. Style segments with ui.segment and state attributes.

Usage

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

const date = shallowRef<CalendarDateValue>(new CalendarDate(2026, 8, 12));
</script>

<template>
  <DateField
    v-model="date"
    :placeholder="new CalendarDate(2026, 8, 1)"
  />
</template>

Examples

Field integration

Wrap Date Field in Field to inherit its name, label relationship, required state, description, native error message, and granular interaction attributes.

<Field
  label="Start date"
  name="start"
  description="Required for scheduling."
  required
>
  <DateField v-model="date" />
</Field>

Validation stays quiet on initial render. It becomes visible after users leave the group, enter an invalid complete date, or submit its form.

Locale order

locale controls segment order, separators, and segment labels. The model remains an @internationalized/date value.

<DateField v-model="date" locale="en-GB" />

For en-GB, focus order is day, month, year. For en-US, it is month, day, year.

Date constraints

Use boundaries for fixed limits and isDateUnavailable for application rules. Invalid dates expose Field error state after interaction.

<DateField
  v-model="date"
  :min-value="new CalendarDate(2026, 8, 10)"
  :max-value="new CalendarDate(2026, 8, 24)"
  :is-date-unavailable="(date) => closedDates.has(date.toString())"
/>

Calendar picker

Set showCalendar to add a keyboard-accessible calendar trigger. Date Field forwards locale, direction, constraints, disabled state, read-only state, and ui.calendar to its built-in Calendar. Selection commits the date and closes the popup.

<DateField v-model="date" show-calendar>
  <template #calendar-trigger>Calendar</template>
</DateField>

Use v-model:calendar-open when popup state must be controlled. Use #calendar to replace the calendar body without replacing positioning, outside-click dismissal, Escape handling, or layer ordering.

<DateField v-model="date" show-calendar>
  <template #calendar="{ value, select, close }">
    <MyCalendar :value="value" @select="select" @cancel="close" />
  </template>
</DateField>

Paste a date

Paste a date containing three numeric groups into any segment. The component recognizes ISO year-first values such as 2026-11-24 regardless of the visible locale order.

Native form submission

Set name on the component or inherit it from Field. A complete value submits as an ISO calendar date.

<form @submit.prevent="submit">
  <DateField v-model="date" name="start" required />
  <button>Submit</button>
</form>

Cancel changes

value-change fires before the model updates. Canceling restores segment text to the controlled value.

<DateField
  v-model="date"
  @value-change="(next, details) => {
    if (next && blockedDates.has(next.toString())) details.cancel()
  }"
/>

Read-only and disabled

Read-only segments stay focusable for inspection but cannot change. Disabled segments leave the tab sequence and the hidden input is excluded from form submission.

<DateField v-model="date" read-only />
<DateField v-model="date" disabled />

Reactive validation

Changing min/max, required state, unavailable-date predicates, or the controlled value updates native custom validity without requiring another keystroke. Error presentation still follows interaction/submission state. Native reset restores the initial segments unless canceled.

The optional calendar registers as a logical popup branch when used inside an Akaza modal, including when teleported to body.

API Reference

Model

Props

Date Field accepts calendar dates at day granularity. Use Time Field for clock values.

Emits

Value details.reason can be input, keyboard, paste, blur, clear, or calendar. Calendar-open reasons include trigger, select, escape, and outside-click.

Slots

Methods

UI Options

Styling Hooks

Plain class applies to the Date Field root. Use ui.segment for generated inputs and data variants for state styling.

Keyboard

Each editable part uses role="spinbutton" with aria-valuemin, aria-valuemax, aria-valuenow, and a localized accessible label. Touch users can tap and edit any segment with the numeric keyboard.

Partial segment text remains internal. Date Field updates v-model only after day, month, and year are complete and valid.