Date Range Field
Enter start and end dates in separate editable fields.
Demos
Usage
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'
const items = [
{ value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>
<template>
<Accordion :items="items" />
</template>
Typing and calendar selection
Set :show-calendar="false" for a typing-only range. Bind v-model:calendar-open to control calendar visibility.
Click a date segment to type or use the calendar button to choose a date. Focus and text selection use the neutral secondary fill with its paired foreground. A subtle ring marks the active segment. Slashes have their own spacing. The calendar opens outside the preview frame and follows the same size as the field.
Installation
Complete the shared installation. Copy DateRangeField.vue and index.ts into app/components/ui/date-range-field/. Also copy the required components: Calendar, Date Field.
<script setup lang="ts">
import {
DateRangeField as Primitive,
Popover,
type CalendarModelValue,
type AkazaChangeEventDetails,
} from 'akaza-ui'
import { computed, ref, shallowRef, watch, useAttrs, useTemplateRef } from 'vue'
import { cn, mergeRecipeSlots } from '../../../utils/ui'
import { Calendar, calendarVariants } from '../calendar'
import { dateFieldVariants, resolveDateFieldVariants } from '../date-field'
import uiConfig from '../ui.config'
import {
dateRangeFieldVariants,
resolveDateRangeFieldVariants,
type DateRangeFieldProps,
type DateRangeFieldSlots,
} from './index'
defineOptions({ inheritAttrs: false })
// Preserve Akaza defaults when optional props, including Boolean aliases, are omitted.
const props = withDefaults(defineProps<DateRangeFieldProps>(), {
showCalendar: true,
calendarLabel: 'Choose date range',
calendarOpen: undefined,
id: undefined,
name: undefined,
startName: undefined,
endName: undefined,
locale: undefined,
dir: undefined,
placeholder: undefined,
minValue: undefined,
maxValue: undefined,
isDateUnavailable: undefined,
allowNonContiguousRanges: undefined,
maximumDays: undefined,
fixedDate: undefined,
required: undefined,
disabled: undefined,
readOnly: undefined,
invalid: undefined,
selectOnFocus: undefined,
autoAdvance: undefined,
startLabel: undefined,
endLabel: undefined,
ariaLabel: undefined,
ariaLabelledby: undefined,
ariaDescribedby: undefined,
ui: undefined,
modelValue: undefined,
})
defineSlots<DateRangeFieldSlots>()
const attrs = useAttrs()
const emit = defineEmits<{
'update:calendarOpen': [open: boolean]
'update:modelValue': [value: import('akaza-ui').CalendarDateRange]
}>()
const localValue = shallowRef<import('akaza-ui').CalendarDateRange>({})
const value = computed({
get: () => props.modelValue ?? localValue.value,
set: (value) => {
localValue.value = value
emit('update:modelValue', value)
},
})
const localCalendarOpen = ref(false)
const calendarOpen = computed({
get: () => props.calendarOpen ?? localCalendarOpen.value,
set: (open) => {
localCalendarOpen.value = open
emit('update:calendarOpen', open)
},
})
watch(
() => [props.showCalendar, props.disabled, props.readOnly],
() => {
if (!props.showCalendar || props.disabled || props.readOnly) calendarOpen.value = false
},
)
function openCalendar(event: MouseEvent) {
if (
props.showCalendar &&
!props.disabled &&
!props.readOnly &&
(event.target as HTMLElement).closest('.akaza-date-field-segments')
)
calendarOpen.value = true
}
const primitive = useTemplateRef<InstanceType<typeof Primitive>>('primitive')
function selectRange(value: CalendarModelValue, details: AkazaChangeEventDetails) {
details.cancel()
if (!value || Array.isArray(value) || !('start' in value || 'end' in value)) return
const range = value as import('akaza-ui').CalendarDateRange
if (primitive.value?.setValue(range, 'calendar', details.event) && range.start && range.end)
calendarOpen.value = false
}
const resolved = computed(() => resolveDateRangeFieldVariants(props, uiConfig))
const styles = computed(() => dateRangeFieldVariants(resolved.value))
const mergedUi = computed(() => {
const overrides = props.ui as Record<string, string | undefined> | undefined
const flat = Object.fromEntries(
Object.entries(styles.value)
.filter(([part]) => !['startField', 'endField', 'calendar', 'calendarTrigger'].includes(part))
.map(([part, style]) => [
part,
cn(style(), overrides?.[part], part === 'root' ? props.class : undefined),
]),
)
return {
...flat,
popover: flat.popover,
fields: flat.fields,
calendarContent: flat.calendarContent,
calendarTrigger: cn(
dateFieldVariants(resolveDateFieldVariants(resolved.value, uiConfig)).calendarTrigger(),
props.ui?.calendarTrigger,
),
calendar: mergeRecipeSlots(
calendarVariants({ size: resolved.value.size, rangeColor: resolved.value.rangeColor }),
{
...props.ui?.calendar,
root: cn(styles.value.calendar(), props.ui?.calendar?.root),
},
),
startField: {
...mergeRecipeSlots(
dateFieldVariants(resolveDateFieldVariants(resolved.value, uiConfig)),
props.ui?.startField,
),
calendar: mergeRecipeSlots(
calendarVariants({ size: resolved.value.size, rangeColor: resolved.value.rangeColor }),
props.ui?.startField?.calendar,
),
},
endField: {
...mergeRecipeSlots(
dateFieldVariants(resolveDateFieldVariants(resolved.value, uiConfig)),
props.ui?.endField,
),
calendar: mergeRecipeSlots(
calendarVariants({ size: resolved.value.size, rangeColor: resolved.value.rangeColor }),
props.ui?.endField?.calendar,
),
},
}
})
const primitiveProps = computed(() => {
const {
class: _class,
ui: _ui,
size: _size,
rangeColor: _rangeColor,
variant: _variant,
showCalendar: _showCalendar,
calendarOpen: _calendarOpen,
calendarLabel: _calendarLabel,
...native
} = props
return native
})
defineExpose({
get clear() {
return primitive.value!.clear
},
get focusEnd() {
return primitive.value!.focusEnd
},
get focusStart() {
return primitive.value!.focusStart
},
get setValue() {
return primitive.value!.setValue
},
})
</script>
<template>
<Popover
v-model="calendarOpen"
teleport="body"
align="start"
:ui="{
root: mergedUi.popover,
content: mergedUi.calendarContent,
}"
>
<template #trigger="scope">
<div :class="mergedUi.fields">
<component
:is="Primitive"
ref="primitive"
v-bind="{ ...primitiveProps, ...attrs }"
:ui="mergedUi"
v-model="value"
@click="openCalendar"
>
<template v-for="(_, name) in $slots" #[name]="scope"
><slot :name="name as keyof DateRangeFieldSlots" v-bind="scope ?? {}"
/></template>
</component>
<button
v-if="showCalendar"
type="button"
:class="mergedUi.calendarTrigger"
:disabled="disabled || readOnly"
v-bind="scope.triggerProps"
:aria-label="calendarLabel"
:aria-expanded="calendarOpen"
@click="scope.toggle($event)"
>
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="1.75"
aria-hidden="true"
>
<path
d="M8 2v4m8-4v4M3 10h18M5 4h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2Z"
/>
</svg>
</button>
</div>
</template>
<template #content>
<div role="dialog" :aria-label="calendarLabel">
<Calendar
:model-value="value"
selection-mode="range"
:range-color="resolved.rangeColor"
:locale="locale"
:dir="dir"
:min-value="minValue"
:max-value="maxValue"
:is-date-unavailable="isDateUnavailable"
:allow-non-contiguous-ranges="allowNonContiguousRanges"
:maximum-days="maximumDays"
:fixed-date="fixedDate"
:placeholder="placeholder"
:size="resolved.size"
:initial-focus="false"
:disabled="disabled"
:read-only="readOnly"
:ui="mergedUi.calendar"
:calendar-label="calendarLabel"
@value-change="selectRange"
/>
</div>
</template>
</Popover>
</template>
API
Variants and defaults
| Prop | Values | Default |
|---|---|---|
size | xs, sm, md, lg, xl | sm |
variant | outline, soft, bare | outline |
See Range selection for preview fills and primary-colored endpoints.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
rangeColor | "secondary" | "accent" | "secondary" | Preview and committed middle fill; endpoints use primary. |
calendarLabel | string | "Choose date range" | Accessible label for the calendar button and popup. |
showCalendar | boolean | true | Offer a range calendar alongside segmented typing. |
calendarOpen | boolean | false | Calendar visibility, also available as v-model:calendar-open. |
id | string | Field/generated id | ID assigned to the first start segment. |
name | string | Field name | Base native form name used to create .start and .end names. |
startName | string | ${name}.start | Explicit start form field name. |
endName | string | ${name}.end | Explicit end form field name. |
locale | string | "en-US" | Segment order, separators, and accessible labels for both endpoints. |
dir | "ltr" | "rtl" | "ltr" | Reading direction and segment arrow behavior. |
placeholder | CalendarDateValue | today | Date context used while endpoint segments are partial. |
minValue | CalendarDateValue | - | Earliest valid start and endpoint value. |
maxValue | CalendarDateValue | - | Latest valid end and endpoint value. |
isDateUnavailable | (date) => boolean | - | Application rule for unavailable dates. |
allowNonContiguousRanges | boolean | false | Allows unavailable dates inside, but not at boundaries. |
maximumDays | number | - | Maximum inclusive range length. |
fixedDate | "start" | "end" | - | Makes one endpoint read-only. |
required | boolean | false | Requires both endpoints for native validity. |
disabled | boolean | false | Disables editing and native form participation. |
readOnly | boolean | false | Keeps segments focusable but blocks changes. |
invalid | boolean | false | Forces invalid styling and ARIA state. |
selectOnFocus | boolean | true | Selects focused segment text. |
autoAdvance | boolean | true | Advances after a segment reaches full length. |
startLabel | string | "Start date" | Accessible label for the start Date Field. |
endLabel | string | "End date" | Accessible label for the end Date Field. |
ariaLabel | string | "Date range" | Root group label without an external label. |
ariaLabelledby | string | Field label ID | External label relationship. |
ariaDescribedby | string | Field description/error IDs | External description relationship. |
ui | DateRangeFieldUi | - | Classes for generated structural parts. |
Slots
| Slot | Props | Description |
|---|---|---|
start-literal | value | Replaces locale separators inside the start endpoint. |
separator | - | Replaces the visual separator between endpoints. |
end-literal | value | Replaces locale separators inside the end endpoint. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | CalendarDateRange | Fires after an accepted endpoint change or clear. |
value-change | (range, details) | Fires before model changes. details.cancel() prevents the change. |
value-commit | (range, details) | Fires after accepted endpoint input, keyboard, paste, or blur commits. |
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".