Date Field
Enter a date by typing or selecting from a calendar.
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
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 DateField.vue and index.ts into app/components/ui/date-field/. Also copy the required components: Calendar.
<script setup lang="ts">
import { DateField as Primitive } from 'akaza-ui'
import { computed, nextTick, useAttrs, useTemplateRef } from 'vue'
import { cn, mergeRecipeSlots } from '../../../utils/ui'
import { calendarVariants } from '../calendar'
import uiConfig from '../ui.config'
import {
dateFieldVariants,
resolveDateFieldVariants,
type DateFieldProps,
type DateFieldSlots,
} from './index'
defineOptions({ inheritAttrs: false })
// Preserve Akaza defaults when optional props, including Boolean aliases, are omitted.
const props = withDefaults(defineProps<DateFieldProps>(), {
id: undefined,
name: undefined,
locale: undefined,
dir: undefined,
placeholder: undefined,
minValue: undefined,
maxValue: undefined,
isDateUnavailable: undefined,
required: undefined,
disabled: undefined,
readOnly: undefined,
invalid: undefined,
selectOnFocus: undefined,
autoAdvance: undefined,
showCalendar: true,
calendarLabel: undefined,
calendarSide: undefined,
calendarAlign: undefined,
calendarSideOffset: undefined,
calendarTeleport: 'body',
ariaLabel: undefined,
ariaLabelledby: undefined,
ariaDescribedby: undefined,
ui: undefined,
modelValue: undefined,
calendarOpen: undefined,
})
defineSlots<DateFieldSlots>()
const attrs = useAttrs()
const resolved = computed(() => resolveDateFieldVariants(props, uiConfig))
const styles = computed(() => dateFieldVariants(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]) => !['calendar'].includes(part))
.map(([part, style]) => [
part,
cn(style(), overrides?.[part], part === 'root' ? props.class : undefined),
]),
)
return {
...flat,
calendar: mergeRecipeSlots(calendarVariants({ size: resolved.value.size }), {
...props.ui?.calendar,
root: cn(styles.value.calendar(), props.ui?.calendar?.root),
}),
}
})
const primitiveProps = computed(() => {
const { class: _class, ui: _ui, size: _size, variant: _variant, ...native } = props
return native
})
const primitive = useTemplateRef<InstanceType<typeof Primitive>>('primitive')
async function onFieldClick(event: MouseEvent) {
const target = event.target as HTMLElement
if (
props.showCalendar &&
!props.disabled &&
!props.readOnly &&
target.closest('.akaza-date-field-segments')
) {
primitive.value?.openCalendar(event)
// Calendar initial focus belongs to its button; clicking a segment must keep typing focus.
await nextTick()
await nextTick()
target.focus({ preventScroll: true })
}
}
defineExpose({
get validationState() {
return primitive.value!.validationState
},
get clear() {
return primitive.value!.clear
},
get closeCalendar() {
return primitive.value!.closeCalendar
},
get focus() {
return primitive.value!.focus
},
get openCalendar() {
return primitive.value!.openCalendar
},
get setValue() {
return primitive.value!.setValue
},
get toggleCalendar() {
return primitive.value!.toggleCalendar
},
})
</script>
<template>
<component
:is="Primitive"
ref="primitive"
v-bind="{ ...primitiveProps, ...attrs }"
:ui="mergedUi"
@click="onFieldClick"
>
<template v-for="(_, name) in $slots" #[name]="scope"
><slot :name="name as keyof DateFieldSlots" v-bind="scope ?? {}"
/></template>
<template v-if="!$slots['calendar-trigger']" #calendar-trigger
><svg
class="size-4 shrink-0"
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
></template>
</component>
</template>
API
Variants and defaults
| Prop | Values | Default |
|---|---|---|
size | xs, sm, md, lg, xl | sm |
variant | outline, soft, bare | outline |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | generated | ID assigned to the first locale-ordered segment. |
name | string | Field name | Native form field name. |
locale | string | "en-US" | Segment order, separators, and accessible labels. |
dir | "ltr" | "rtl" | "ltr" | Reading direction and horizontal arrow behavior. |
placeholder | CalendarDateValue | today | Date context used while segments are empty or partial. |
minValue | CalendarDateValue | — | Earliest valid complete date. |
maxValue | CalendarDateValue | — | Latest valid complete date. |
isDateUnavailable | (date) => boolean | — | Marks complete dates invalid by application rule. |
required | boolean | false | Requires a complete date for native form validation. |
disabled | boolean | false | Disables segments 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 current segment text when focused. |
autoAdvance | boolean | true | Moves focus after a segment reaches its maximum length. |
showCalendar | boolean | true | Adds a trigger and positioned Calendar popup. |
calendarLabel | string | "Choose date" | Trigger and popup accessible label. |
calendarSide | "top" | "right" | "bottom" | "left" | "bottom" | Preferred popup side with collision flipping. |
calendarAlign | "start" | "center" | "end" | "start" | Popup alignment against Date Field. |
calendarSideOffset | number | 6 | Trigger-to-popup gap in pixels. |
calendarTeleport | string | false | "body" | Teleport target; false keeps popup beside Date Field. |
ariaLabel | string | "Date" | Root group label when no external label exists. |
ariaLabelledby | string | Field label ID | External label relationship. |
ariaDescribedby | string | Field description/error IDs | External description relationship. |
ui | DateFieldUi | — | Classes for generated structural parts. |
Date Field accepts calendar dates at day granularity. Use Time Field for clock values.
Slots
| Slot | Props | Description |
|---|---|---|
literal | value | Replaces visible locale separator content without changing segment behavior. |
calendar-trigger | isOpen, open, close, toggle | Replaces optional trigger content. Actions accept native event-first handlers. |
calendar | value, select, close | Replaces built-in Calendar content while retaining popup behavior. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | CalendarDateValue | undefined | Fires after an accepted complete value or clear. |
value-change | (value, details) | Fires before model changes. details.cancel() prevents the change. |
value-commit | (value, details) | Fires after accepted input, keyboard, paste, blur, or clear commits. |
update:calendarOpen | boolean | Fires after accepted calendar popup changes. |
calendar-open-change | (open, details) | Fires before popup changes. details.cancel() prevents the change. |
Value details.reason can be input, keyboard, paste, blur, clear, or calendar. Calendar-open reasons include trigger, select, escape, and outside-click.
Keyboard
| Key | Behavior |
|---|---|
| Number keys | Edit the focused segment; full segments can auto-advance. |
ArrowUp / ArrowDown | Increment or decrement the focused segment with wrapping. |
PageUp / PageDown | Increment or decrement by 10. |
Home / End | Set the focused segment to its minimum or maximum. |
ArrowLeft / ArrowRight | Move focus between locale-ordered segments, direction-aware in RTL. |
Backspace | Clears native text; from an empty segment, moves to the previous segment. |
Enter / Space on calendar trigger | Opens or closes Calendar. |
Escape in Calendar | Closes popup and restores trigger focus. |
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.