ODatepicker

ODatepicker is a labelled calendar field for controlled local-day, range, week, month, and multiple-date selection.

Usage

Step by step

1. Import ODatepicker from the ooko-ui/datepicker public subpath.
2. Bind the controlled model with v-model and provide the required label.
3. Type a date in the format indicated by the field or open the calendar to make the same selection. The locale prop controls that visible format.

Example

The rendered example and its source come from the same Vue single-file component.

Appointment date

Selected: 15/09/2026.

Interactive playground

Change the selection type, field state, and calendar options. The preview updates immediately.

Example date

Selected: 15/09/2026.

Type the locale format, or open the calendar.

Type daterangeweekmonthmultiple Size smmdLabel Locale English (UK)English (US)FrançaisHint Error Disabled Read-only Required Hide label Clearable Display week numbers

Props

Prop	Type	Default	Description
size	OokoFormControlSize	"md"	Controls the datepicker's form-control scale.
label	string	undefined	Visible or visually hidden accessible label.
id	string	undefined	Text-input identifier; a hydration-safe identifier is generated when omitted.
name	string	undefined	Native form field name and OForm validation key.
hint	string	undefined	Persistent field guidance.
error	string	undefined	Controlled validation error.
validation	OokoValidationBinding	undefined	Explicit binding created by useOokoValidation.
hideLabel	boolean	false	Visually hides the label while preserving its accessible name.
required	boolean	false	Requires a selection.
disabled	boolean	false	Prevents interaction and native form submission.
readonly	boolean	false	Keeps the text input focusable while preventing selection changes.
clearable	boolean	false	Displays an empty-value action next to the input.
icon	Component	undefined	Vue component rendered as a decorative field icon.
iconPosition	OFieldIconPosition	undefined	Places the decorative field icon before or after the datepicker controls.
placeholder	string	undefined	Content shown when no value is selected.
locale	string	"en-GB"	BCP 47 locale used to format and parse visible calendar dates.
minDate	string	undefined	Earliest selectable local calendar day, inclusive.
maxDate	string	undefined	Latest selectable local calendar day, inclusive.
displayWeekNumber	boolean	false	Displays ISO week numbers beside calendar rows.
type	ODatepickerType	"date"	Selects one day, range, ISO week, month, or multiple local days.
modelValue	ODatepickerValue	undefined	Controlled value whose shape corresponds to the selected type.

Events

Event	Payload	Description
update:modelValue	string | ODatepickerRange | readonly ODatepickerDate[] | null	Emits the controlled selection after a complete valid typed date, calendar choice, or clear action.

Slots

Slot	Props	Description
icon	none	Provides custom decorative field icon markup and overrides the icon prop.

Related types

Type	Definition
ODatepickerDate	type ODatepickerDate = string;
ODatepickerRange	type ODatepickerRange = readonly [ODatepickerDate, ODatepickerDate];
ODatepickerType	type ODatepickerType = "date" | "multiple" | "month" | "range" | "week";
ODatepickerValue	type ODatepickerValue = ODatepickerDate | ODatepickerRange | readonly ODatepickerDate[] | null;

CSS custom properties

Custom property	Default	Description
--o-datepicker-panel-width	20rem	Maximum calendar popup width.
--o-datepicker-panel-radius	var(--o-radius-surface)	Calendar popup corner radius.
--o-datepicker-day-size	2.25rem	Calendar day control minimum size.

Override example

:root {
  --o-datepicker-panel-width: 24rem;
  --o-datepicker-day-size: 2.5rem;
}

Accessibility

• The required label names the editable text input; hideLabel preserves that accessible name.
• The input opens a labelled nonmodal dialog on click or with Arrow Down. Escape closes it while preserving input focus. Date grids support arrow keys, Home, End, Page Up, Page Down, Enter, and Space; month and year grids expose their active cell during arrow-key navigation. The week dialog exposes a list of selectable week ranges.
• A click on a day, month, or year segment selects that segment; a click beside the text selects the full value. Up and Down adjust the segment containing the caret or the selected segment, while Left and Right move between selected segments. The datepicker does not render a separate calendar trigger.
• The input automatically inserts its locale separators while typing. locale="fr-FR" uses DD/MM/YYYY; en-GB uses the same day-first order; en-US uses MM/DD/YYYY.
• In single-date mode, typing replaces the active section without shifting the others. A first digit that cannot begin a two-digit day or month is zero-padded (4 becomes 04, 9 becomes 09 for a month). Completing a section selects the next one in locale order; the day limit follows the displayed month and year.
• A complete, valid single date updates the controlled model and calendar highlight while typing. Incomplete, invalid, or out-of-bounds text preserves the last accepted selection. Bounds errors identify the earliest or latest allowed date rather than requesting a different format.
• The calendar header opens a direct month view or a decade-based year view. In range mode, the first click anchors either endpoint and hovering previews the ordered range in either direction, replacing the previous highlight. Tentative and accepted ranges form continuous bands, with only the outer endpoint corners rounded.
• Week mode announces and displays a list of ISO week numbers with their From … to … ranges. The field keeps that week label and range when focused. Month mode displays its localized month name and year. Multiple mode renders every selected day as a removable chip.
• Invalid typed values remain visible, set aria-invalid, and expose an inline validation message. Dates outside minDate and maxDate cannot be typed or selected.
• Disabled input uses native disabled behavior. Read-only input remains focusable and does not change the controlled model.
• Focus is visibly indicated, and forced-colors mode maintains calendar control borders and selected-state contrast.

Behavior and edge cases

• Values are ISO local calendar strings rather than Date objects, which makes server rendering and time-zone handling deterministic. locale changes only the visible format, never the emitted model. The component deliberately does not recreate Orion's optional time editor.
• date, week, and month emit a string or null; range emits an ordered two-item tuple or null; multiple emits an ordered string array. Week values are the Monday that starts the ISO week.
• A range click first sets a temporary start; the second click emits the ordered inclusive range and closes the dialog. Typing a range emits once its two valid bounds are parsed.
• Opening the popup from the input preserves input focus. Leaving the datepicker closes the popup; moving focus into its calendar keeps it open. Selecting a single date, week, month, or complete range closes it and restores focus to the input. Multiple selection stays open.
• Leaving the empty typing area in multiple mode preserves the selected chips. A required multiple-date field validates the selected collection, not the text used to add another date.
• Parent model updates replace the displayed text even while focused. Valid calendar choices clear previous typing errors; unchanged month and week displays remain valid on Enter and blur.
• Form submission uses hidden ISO values for the selected dates. A disabled component contributes no values.