Options
One block per prop — what it does, and what it looks like set.
Model value
modelValue is the selected date as a real Date — or a { start, end } object once range is set, and null for nothing chosen. Pass it to control the selection yourself; the trigger's formatted text is derived from it and locale, so there's no separate string to keep in step.
Default value
defaultValue is the date the picker starts on while it still owns its own state. It's the natural place for “today” or the start of the current period, so the calendar opens somewhere useful rather than empty.
Placeholder
placeholder is what the trigger shows before a date is picked, defaulting to “Select a date”. Change it when the field wants a particular kind of date — a deadline, a birthday — since it's the only instruction the closed trigger carries.
Disabled
disabled disables the trigger, preventing the calendar from opening.
Clearable
clearable shows a button to clear the selected value.
Variant
variant picks between the ringed outline trigger and the lightly tinted soft one, which has its own section below.
Icon
icon is the glyph in the trigger, calendar by default. Swapping it is a way to say what kind of date the field holds — a clock face for a deadline, a flag for a milestone — without changing the copy.
Range
range switches the calendar to picking a start and an end instead of a single day, which also changes modelValue to a { start, end } object.
Min
min is the earliest selectable day — everything before it is disabled in the calendar rather than hidden, so the reader can still see where the boundary falls. The example below is bounded to the current month.
Max
max is the other boundary — the latest selectable day, with everything after it disabled. Pairing it with min is how you fence a picker to a booking window or a reporting period.
Locale
locale is the BCP 47 tag used to format the trigger's date, the month heading and the weekday row. It doesn't change which day the week starts on being derived — it's the whole formatting story — so set it from the reader's locale rather than the content's.
Markers
markers flags days with a small dot under their number, forwarded straight through to the Calendar popover — appointments, deadlines, anything worth noticing before opening the day. Open the calendar below to see it.
Content
content positions the calendar popover relative to the field: side, align and sideOffset. Reach for it when the field sits low on the page, where the calendar would otherwise open past the fold.
Open
open controls whether the calendar popover is showing. Pass it to drive the calendar from your own state and bind it with v-model:open so the trigger still works; omit it and the component manages that itself.
Default open
defaultOpen starts the calendar expanded on mount while leaving the open state uncontrolled — worth it on a step whose only question is the date, and disruptive anywhere the field is one of several.
Examples
The component in real use: compositions that answer "how do I build X with this", rather than one prop at a time.
`variant="soft"`
A lightly tinted background with no ring until focused — a lower-emphasis alternative to outline.
Wrapped in `FormField`
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
Date | DateRangeValue | nullCalendarMarker[]DateInputContentProps{ align: 'start', side: 'bottom', sideOffset: 8 }booleanEmits
update:modelValue[value: ModelValue]update:open[value: boolean]Types
type ModelValue = Date | DateRangeValue | null;interface DateRangeValue {
start: Date | null;
end: Date | null;
}interface DateInputContentProps {
align?: "start" | "center" | "end";
side?: "bottom" | "top";
sideOffset?: number;
}interface CalendarMarker {
/**
* The day this marker lands on — only its year/month/day are read, so the time of day is ignored.
*/
date: Date;
/**
* @defaultValue 'primary'
*/
color?: MarkerColor;
}