Date Range Picker

DateRangePicker combines Date Range Field and Calendar. Users can type either endpoint or select a range from the popup.

Use Date Range Field when you do not need a calendar popup.

Anatomy

• root: Generated picker root containing field and trigger.
• field: Generated Date Range Field with all endpoint behavior.
• #start-literal: Replaces start endpoint locale separators.
• #separator: Replaces endpoint separator.
• #end-literal: Replaces end endpoint locale separators.
• #trigger: Calendar trigger content with open, close, and toggle actions.
• content: Teleported, positioned role="dialog" popup.
• #calendar: Replaces built-in Calendar while retaining popup infrastructure.
• #previous, #heading, #next, #weekday, #day, #footer: Customize built-in Calendar content.
• #close: Optional close-button content, rendered when slot or closeLabel exists.

Date Range Picker exposes one component with slots for its generated parts.

Usage

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

const range = shallowRef<CalendarDateRange>({});
</script>

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

Examples

Multiple months

Render adjacent months and navigate by the visible page. Add fixedWeeks when the popup should keep a stable six-week grid height between months.

<DateRangePicker
  v-model="range"
  :number-of-months="2"
  paged-navigation
  fixed-weeks
/>

Close behavior

Picker stays open after a complete selection by default so users can inspect or adjust both boundaries. Add closeOnSelect when a finished range should close immediately, or provide closeLabel for an explicit generated close button.

<DateRangePicker v-model="range" close-on-select />
<DateRangePicker v-model="range" close-label="Done" />

Constraints and unavailable dates

Date Range Field and Calendar receive the same boundaries, unavailable-date rule, non-contiguous setting, maximum length, disabled state, and read-only state.

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

Use isDateDisabled for Calendar-only selection rules. Use isDateUnavailable when typed endpoint and full-range validity must enforce the same rule.

Fixed endpoint

Fix the start or end while the other boundary remains editable through both segments and Calendar.

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

Controlled popup

Use v-model:open and the cancelable open-change event when application state owns dismissal.

<DateRangePicker
  v-model="range"
  v-model:open="open"
  @open-change="(next, details) => {
    if (!next && hasUnsavedDraft) details.cancel()
  }"
/>

Custom trigger and calendar parts

Slots change visuals without replacing ARIA, focus, positioning, collision handling, or selection behavior.

<DateRangePicker v-model="range">
  <template #trigger="{ isOpen }">
    <CalendarIcon :data-open="isOpen" />
  </template>
  <template #day="{ label, unavailable }">
    <span :class="{ 'line-through': unavailable }">{{ label }}</span>
  </template>
</DateRangePicker>

Use #calendar only when replacing the entire calendar is necessary. That slot receives current value and close while the picker retains popup behavior.

API Reference

Models

Props

Date Range Picker accepts Date Range Field props id, name, startName, endName, locale, dir, minValue, maxValue, isDateUnavailable, allowNonContiguousRanges, maximumDays, fixedDate, required, disabled, readOnly, invalid, selectOnFocus, autoAdvance, endpoint labels, and ARIA relationships.

Emits

Open reasons include trigger, select, escape, outside-click, and programmatic. Value reasons match Date Range Field plus calendar.

Slots

Methods

UI Options

Styling Hooks

Nested field and calendar parts retain their own exact semantic classes and data attributes. Plain class applies to picker root. Use ui.content for teleported popup styling.

Keyboard and focus

Field segments follow Date Field's spinbutton keyboard pattern. Calendar uses roving day focus, arrow keys, week boundaries, month/year paging, and Enter/Space selection. Escape closes only the top dismissable layer and restores trigger focus. Outside pointer interaction closes the popup; touch activation uses native button behavior.