DatePicker

A date field with a calendar popover. The value is a string in the picker's format, yyyy-mm-dd by default, so it can go straight into URL params or model inputs. Typed input commits on blur or Enter and is normalized to the format (2026-5-4 becomes 2026-05-04). Text that doesn't parse, or falls outside min/max, is marked aria-invalid and not emitted.

The calendar header has month and year dropdowns for jumping to a distant date, next to the previous/next month arrows. The year list runs from min to max, or 50 years either side of the opened date when unbounded, and months outside min/max are disabled.

Examples

Start date

Value: 2026-05-14

<script setup>
import { ref } from "vue";
const start = ref("2026-05-14");
</script>

<DatePicker v-model="start" label="Start date" hint="The date of day 0" />

Custom formats

format sets both the displayed text and the model value (see display format to split them). The placeholder defaults to the format string.

Token	Output
yyyy	2026
yy	26
mmmm	January
mmm	Jan
mm	01
m	1
dd	05
d	5

Tokens are case-insensitive (YYYY-MM-DD works), and every other character is a literal. Parsing is lenient: numbers can be typed with or without padding, month names ignore case, and yy reads as 2000–2099. Month names are English.

US format

Month name

Values: 05/14/2026, May 14, 2026

<DatePicker v-model="us" label="US format" format="mm/dd/yyyy" />
<DatePicker v-model="named" label="Month name" format="mmm d, yyyy" />

Display format

To show one format but keep another as the value, set display-format. The input shows and accepts display-format, while v-model, min, max, and reference-date stay in format. This keeps a friendly field over an ISO value for URLs and model inputs.

Report date

Value: 2026-05-14

<DatePicker v-model="iso" label="Report date" display-format="mmmm d, yyyy" />

Min and max

min and max take dates in the same format. Days outside the range are disabled in the calendar, and typed dates outside it are flagged as invalid.

Campaign start

<DatePicker
  v-model="bounded"
  label="Campaign start"
  min="2026-05-14"
  max="2026-08-31"
/>

Clearing

An empty field emits "". Add clearable for a clear button, or required to flag an empty field as invalid and keep the last value.

End date

Value: ""

<DatePicker v-model="optional" label="End date" clearable />

Model time

Simulations often count time in days from a start date. Pass reference-date (the date of day 0, in format) to add a day field under the calendar: it shows the current value as a day, and entering a day sets the date that many days after the reference (negative days go before it). The reference day is marked with a dot in place of today. time-label sets the day field's label (default "Day"), and its hint names the reference date.

Policy start

Value: 2026-06-01

<DatePicker
  v-model="policyStart"
  label="Policy start"
  reference-date="2026-05-14"
  time-label="Model day"
/>

Model

Name	Type
v-model	string

Props

Prop	Type	Required	Default
label	string	No	—
hideLabel	boolean	No	—
ariaLabel	string	No	—
hint	string	No	—
format	string	No	DEFAULT_DATE_FORMAT
displayFormat	string	No	—
placeholder	string	No	—
min	string	No	—
max	string	No	—
locale	string	No	—
clearable	boolean	No	—
required	boolean	No	—
referenceDate	string	No	—
timeLabel	string	No	"Day"