Datepicker
A calendar on top of a native date input. The server sends <input type="date">, which already has its own picker and submits an ISO value; on init a button opens a calendar dialog with a grid you can drive from the keyboard, month and year navigation, today and clear actions, and the limits from min and max. Month and weekday names come from the browser's locale data, so the same markup reads right in any language. On coarse pointers the native picker stays, because it is the better tool there.
<div class="iv-field iv-datepicker" data-iv-component="datepicker" data-iv-native="off" style="max-width: 22rem">
<label class="iv-label" for="d-start">Start date</label>
<input class="iv-input" type="date" id="d-start" name="start" min="2026-01-01" max="2026-12-31" value="2026-03-04" aria-describedby="d-start-help">
<p class="iv-field__help iv-u-m-0" id="d-start-help">Demo field: nothing is submitted or stored. Dates are limited to 2026, so days outside that year cannot be picked. Without JavaScript this is the browser date picker; with JavaScript it becomes the calendar below the field. This fixture sets <code>data-iv-native="off"</code> so the calendar shows on phones too, where the default would keep the native picker.</p>
</div>// data-iv-component="datepicker"
{
native: "off",
}Locale and first day of the week
data-iv-locale picks the language of the names and data-iv-first-day the first column; by default both follow the document language. The button labels are options, so they can be translated too.
<div class="iv-stack iv-u-gap-6" style="max-width: 22rem">
<div class="iv-field iv-datepicker" data-iv-component="datepicker" data-iv-native="off" data-iv-locale="es-ES" data-iv-first-day="1" data-iv-open-text="Abrir calendario" data-iv-prev-text="Mes anterior" data-iv-next-text="Mes siguiente" data-iv-today-text="Hoy" data-iv-clear-text="Borrar" data-iv-dialog-text="Elige una fecha">
<label class="iv-label" for="d-es">Fecha de entrada</label>
<input class="iv-input" type="date" id="d-es" name="es" value="2026-03-04" aria-describedby="d-es-help">
<p class="iv-field__help iv-u-m-0" id="d-es-help">Spanish calendar: month and day names come from <code>Intl</code> with <code>data-iv-locale="es-ES"</code>, the week starts on Monday and every button label is translated through options.</p>
</div>
<div class="iv-field iv-datepicker" data-iv-component="datepicker" data-iv-native="off" data-iv-locale="en-US" data-iv-first-day="0">
<label class="iv-label" for="d-us">Check-in date</label>
<input class="iv-input" type="date" id="d-us" name="us" value="2026-03-04" aria-describedby="d-us-help">
<p class="iv-field__help iv-u-m-0" id="d-us-help">American calendar: same component with <code>data-iv-locale="en-US"</code> and the week starting on Sunday. Demo fields: nothing is submitted or stored.</p>
</div>
</div>// data-iv-component="datepicker"
{
native: "off",
locale: "es-ES",
firstDay: 1,
openText: "Abrir calendario",
prevText: "Mes anterior",
nextText: "Mes siguiente",
todayText: "Hoy",
clearText: "Borrar",
dialogText: "Elige una fecha",
}Options
| Option | Attribute | Default | Effect |
|---|---|---|---|
native | data-iv-native | auto | auto keeps the native picker on coarse pointers; on always; off always shows the calendar. |
locale | data-iv-locale | document language | BCP 47 tag for month and weekday names. |
firstDay | data-iv-first-day | -1 | 0 (Sunday) to 6; -1 follows the locale, or Monday when the browser cannot tell. |
openText, prevText, nextText, todayText, clearText, dialogText | data-iv-open-text … | English labels | Accessible names and button texts. |
Methods and events
open(), close(), setValue(iso), clear(), destroy(); read value, date and isOpen. Events: iv:open/iv:close (cancelable) then iv:opened/iv:closed; iv:change (cancelable, detail.value, previousValue, date) then iv:changed. The input also receives input and change.
Keyboard and assistive technology
Left and Right move a day, Up and Down a week, Home and End to the ends of the week, Page Up and Page Down a month, with Shift a year; Enter or Space selects and closes; Escape closes and returns focus to the button. The grid is a real table with one tab stop, the dialog is non-modal and labelled, disabled days are real disabled buttons and the month title is announced when it changes.
Without JavaScript
The native date input does everything: typing, the browser's own picker, min, max and form submission in ISO format.
Common mistakes
- Reading or writing the value in a display format: the input value is always
YYYY-MM-DD. - Forcing the custom calendar on phones: the native one is faster and localised by the system.
- Ranges or times: out of scope; use two fields or a time input.
Class index
Parts and modifiers of this family that the examples above do not show. The full list per stylesheet lives in the reference.
| Class | What it does |
|---|---|
iv-datepicker__header | Month heading with the two navigation buttons. |
iv-datepicker__footer | Row with the today and clear buttons. |
iv-datepicker__weekday | Abbreviated weekday of the grid, taken from Intl. |
iv-datepicker__icon | Calendar glyph of the toggle, drawn with a mask. |
iv-datepicker__day--today | Today's cell: a ring, never colour alone. |
iv-datepicker__day--outside | Day belonging to the previous or next month. |