Skip to content

Date Field

Enter a date by typing or selecting from a calendar.

Demos

Size
Variant

Usage

vue
<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.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm
variantoutline, soft, bareoutline

Props

PropTypeDefaultDescription
idstringgeneratedID assigned to the first locale-ordered segment.
namestringField nameNative form field name.
localestring"en-US"Segment order, separators, and accessible labels.
dir"ltr" | "rtl""ltr"Reading direction and horizontal arrow behavior.
placeholderCalendarDateValuetodayDate context used while segments are empty or partial.
minValueCalendarDateValue—Earliest valid complete date.
maxValueCalendarDateValue—Latest valid complete date.
isDateUnavailable(date) => boolean—Marks complete dates invalid by application rule.
requiredbooleanfalseRequires a complete date for native form validation.
disabledbooleanfalseDisables segments and native form participation.
readOnlybooleanfalseKeeps segments focusable but blocks changes.
invalidbooleanfalseForces invalid styling and ARIA state.
selectOnFocusbooleantrueSelects current segment text when focused.
autoAdvancebooleantrueMoves focus after a segment reaches its maximum length.
showCalendarbooleantrueAdds a trigger and positioned Calendar popup.
calendarLabelstring"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.
calendarSideOffsetnumber6Trigger-to-popup gap in pixels.
calendarTeleportstring | false"body"Teleport target; false keeps popup beside Date Field.
ariaLabelstring"Date"Root group label when no external label exists.
ariaLabelledbystringField label IDExternal label relationship.
ariaDescribedbystringField description/error IDsExternal description relationship.
uiDateFieldUi—Classes for generated structural parts.

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

Slots

SlotPropsDescription
literalvalueReplaces visible locale separator content without changing segment behavior.
calendar-triggerisOpen, open, close, toggleReplaces optional trigger content. Actions accept native event-first handlers.
calendarvalue, select, closeReplaces built-in Calendar content while retaining popup behavior.

Events

EventPayloadDescription
update:modelValueCalendarDateValue | undefinedFires 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:calendarOpenbooleanFires 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

KeyBehavior
Number keysEdit the focused segment; full segments can auto-advance.
ArrowUp / ArrowDownIncrement or decrement the focused segment with wrapping.
PageUp / PageDownIncrement or decrement by 10.
Home / EndSet the focused segment to its minimum or maximum.
ArrowLeft / ArrowRightMove focus between locale-ordered segments, direction-aware in RTL.
BackspaceClears native text; from an empty segment, moves to the previous segment.
Enter / Space on calendar triggerOpens or closes Calendar.
Escape in CalendarCloses 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.