Skip to content
Kimenpre-v1documentation home
Color scheme

ki-date-picker

Use a date picker for bookings and deadlines where the weekday matters. For a known date far away, such as a birth date, use a text field with a format hint or separate date fields. Use a dedicated time field for times.

Theme for this example
Color scheme for this example
<ki-date-picker label="Stay" name="stay" mode="range" confirm locale="en-GB" value="2026-11-12/2026-11-16" min="2026-11-10" max="2026-11-30"></ki-date-picker>

Values and forms

Read the saved ISO date or start/end pair from value or from the ki-change event’s detail.value. A named field submits the same value. min and max include their endpoints. Form reset restores the current value attribute.

People can type an ISO value or the numeric date used by the locale, such as 20/11/2026 in en-GB. Separate localized range endpoints with an en dash or a spaced hyphen. Dates commit when the user leaves the text field or presses Enter. With confirm, calendar picks wait for Apply.

Accessibility

Provide a visible label, and use help-text to show the expected format. Translate choose-label, change-label (with {date}), the month navigation labels, Cancel and Apply when needed. The month heading and weekdays use locale or the page language. The calendar preserves Gregorian ISO dates.

In the date grid, use the arrows to move a day or a week, Home and End for week boundaries, and Page Up and Page Down for months. Add Shift to jump a year. Enter and Space pick the focused date. Escape closes the calendar and returns focus to the text field.

API reference

When to use: Choose a nearby date or date range when the weekday matters, such as a booking, a deadline or a schedule.

When not to use: Enter a known distant date, such as a birth date, or choose a time.

Properties & attributes

AttributePropertyTypeDefaultDescription
apply-labelapplyLabelstring'Apply'Localized label of the confirmation button that saves a complete draft.
cancel-labelcancelLabelstring'Cancel'Localized label of the confirmation button that discards a draft.
change-labelchangeLabelstring'Change date, {date}'Localized name of the trigger when a date is saved. Use {date} for the current selection.
choose-labelchooseLabelstring'Choose date'Localized name of the calendar dialog and of the trigger when no date is saved.
confirmconfirmbooleanfalseRequire Apply before saving picks made in the calendar.
disableddisabledbooleanfalseDisables the text entry and calendar button and excludes the field from form data.
error-texterrorTextstring | undefined–Overrides the message shown when a date is missing, invalid or outside the bounds.
first-day-of-weekfirstDayOfWeeknumber | undefined–First weekday, where Sunday is 0 and Saturday is 6. Defaults to the locale's week start.
help-texthelpTextstring | undefined–A format hint or explanation read with the field. It is replaced by a visible error.
invalid-date-labelinvalidDateLabelstring'Enter a valid date within the allowed range.'Localized fallback message for an impossible, incomplete or out-of-bounds date.
labellabelstring–Visible text and accessible name of the date field. Provide a label for every field.
localelocalestring | undefined–BCP 47 language tag for localized dates and weekday order. Defaults to the page language.
maxmaxstring | undefined–Latest selectable date, inclusive. Use YYYY-MM-DD.
minminstring | undefined–Earliest selectable date, inclusive. Use YYYY-MM-DD.
modemode"range" | "single"'single'Select one date or a range with a start and an end date.
namenamestring | undefined–Form-data key. A range is submitted as a single value.
next-month-labelnextMonthLabelstring'Next month'Localized accessible name of the next-month button.
previous-month-labelpreviousMonthLabelstring'Previous month'Localized accessible name of the previous-month button.
requiredrequiredbooleanfalseRequires a complete date or pair of dates for native form submission.
valuevaluestring''Current ISO date, ISO start/end pair or empty string. The value attribute is the reset default.

Events

EventDetail typeDescription
ki-changeCustomEvent<DatePickerChangeDetail>Reports a changed, committed value in canonical ISO form. Use this for calendar and typed changes.

CSS parts

PartDescription
dayDate button in the calendar grid.
errorLive constraint message replacing help when the field is invalid.
fieldEnclosure of the text field and calendar button.
gridCalendar grid with localized weekdays and date buttons.
helpHelp text associated with the input.
inputNative text entry for a localized date or range.
labelVisible label and accessible name of the text field.
monthLive month and year heading.
popupAnchored non-modal calendar dialog.
triggerButton that opens and closes the calendar.

CSS custom properties

The public styling contract of ki-date-picker: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-control-radius-trackCorner radius of a track containing adjacent controls.
--ki-control-size-smSmall control track height, 32 CSS px at the default root size.
--ki-control-size-touchTouch target size for controls on a coarse pointer.
--ki-date-picker-backdrop-filterComplete filter behind the calendar.
--ki-date-picker-bgFill of the calendar dialog.
--ki-date-picker-bg-imageOptional image layered over the calendar fill.
--ki-date-picker-borderCalendar surface edge.
--ki-date-picker-day-hover-bgHover fill of an available unselected day.
--ki-date-picker-day-hover-fgInk on the hover fill.
--ki-date-picker-day-radiusRadius of a day and the ends of a range.
--ki-date-picker-day-sizeDefault size of a day target.
--ki-date-picker-fgDefault calendar text.
--ki-date-picker-field-bgFill of the text field.
--ki-date-picker-field-fgText, icon and caret of the field.
--ki-date-picker-heading-familyFamily of the calendar month heading.
--ki-date-picker-outside-bgFill behind dates in neighboring months.
--ki-date-picker-outside-fgInk of dates in neighboring months.
--ki-date-picker-radiusCalendar popup corner radius.
--ki-date-picker-range-bgFill of the span between selected endpoints.
--ki-date-picker-range-fgText of dates within the span.
--ki-date-picker-selected-bgFill of a chosen day or range endpoint.
--ki-date-picker-selected-fgText of a chosen day or range endpoint.
--ki-date-picker-shadowCalendar popup elevation.
--ki-date-picker-today-borderOutline of the current date.
--ki-date-picker-weekday-bgFill behind weekday names.
--ki-date-picker-weekday-fgInk of weekday names.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-glyph-size-mdMedium glyph for body content (20px at the default root size).
--ki-layout-spacing-3xlThe 3xl spacing step for a stack or grid gap.
--ki-layout-spacing-lgThe lg spacing step for a stack or grid gap.
--ki-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xlThe xl spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-outline-controlThe boundary of a control that can be EMPTY — field, checkbox, radio, switch. Such a control carries no label inside its own box, so the box IS what identifies it and must clear WCAG 1.4.11's 3:1 against every surface it can sit on (s0-s2). Pinned to an accessibility floor, NOT to a position in the emphasis ramp: rebalancing outline.base/low/med/high must never silently erase a control's edge. MarsUI draws Outline/Black-8 here, but as a bevel over a filled cell on a fixed canvas — transcribed literally it measured 1.19:1 against a fill identical to the page (audit 2026-07-25). Declared deviation.
--ki-outline-danger-high-emsemantic color for outline danger high em.
--ki-surface-transparentTransparent surface backing for a background image that carries its own opacity.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text high em.
--ki-text-supportingSupporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

Open ki-date-picker in Storybook