ki-date-picker
@kimen/elements/ki-date-picker- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
apply-label | applyLabel | string | 'Apply' | Localized label of the confirmation button that saves a complete draft. |
cancel-label | cancelLabel | string | 'Cancel' | Localized label of the confirmation button that discards a draft. |
change-label | changeLabel | string | 'Change date, {date}' | Localized name of the trigger when a date is saved. Use {date} for the current selection. |
choose-label | chooseLabel | string | 'Choose date' | Localized name of the calendar dialog and of the trigger when no date is saved. |
confirm | confirm | boolean | false | Require Apply before saving picks made in the calendar. |
disabled | disabled | boolean | false | Disables the text entry and calendar button and excludes the field from form data. |
error-text | errorText | string | undefined | – | Overrides the message shown when a date is missing, invalid or outside the bounds. |
first-day-of-week | firstDayOfWeek | number | undefined | – | First weekday, where Sunday is 0 and Saturday is 6. Defaults to the locale's week start. |
help-text | helpText | string | undefined | – | A format hint or explanation read with the field. It is replaced by a visible error. |
invalid-date-label | invalidDateLabel | string | 'Enter a valid date within the allowed range.' | Localized fallback message for an impossible, incomplete or out-of-bounds date. |
label | label | string | – | Visible text and accessible name of the date field. Provide a label for every field. |
locale | locale | string | undefined | – | BCP 47 language tag for localized dates and weekday order. Defaults to the page language. |
max | max | string | undefined | – | Latest selectable date, inclusive. Use YYYY-MM-DD. |
min | min | string | undefined | – | Earliest selectable date, inclusive. Use YYYY-MM-DD. |
mode | mode | "range" | "single" | 'single' | Select one date or a range with a start and an end date. |
name | name | string | undefined | – | Form-data key. A range is submitted as a single value. |
next-month-label | nextMonthLabel | string | 'Next month' | Localized accessible name of the next-month button. |
previous-month-label | previousMonthLabel | string | 'Previous month' | Localized accessible name of the previous-month button. |
required | required | boolean | false | Requires a complete date or pair of dates for native form submission. |
value | value | string | '' | Current ISO date, ISO start/end pair or empty string. The value attribute is the reset default. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<DatePickerChangeDetail> | Reports a changed, committed value in canonical ISO form. Use this for calendar and typed changes. |
CSS parts
| Part | Description |
|---|---|
day | Date button in the calendar grid. |
error | Live constraint message replacing help when the field is invalid. |
field | Enclosure of the text field and calendar button. |
grid | Calendar grid with localized weekdays and date buttons. |
help | Help text associated with the input. |
input | Native text entry for a localized date or range. |
label | Visible label and accessible name of the text field. |
month | Live month and year heading. |
popup | Anchored non-modal calendar dialog. |
trigger | Button 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.
| Token | Description |
|---|---|
--ki-control-border-width | Stroke width of the boundary of a compact control. |
--ki-control-radius-track | Corner radius of a track containing adjacent controls. |
--ki-control-size-sm | Small control track height, 32 CSS px at the default root size. |
--ki-control-size-touch | Touch target size for controls on a coarse pointer. |
--ki-date-picker-backdrop-filter | Complete filter behind the calendar. |
--ki-date-picker-bg | Fill of the calendar dialog. |
--ki-date-picker-bg-image | Optional image layered over the calendar fill. |
--ki-date-picker-border | Calendar surface edge. |
--ki-date-picker-day-hover-bg | Hover fill of an available unselected day. |
--ki-date-picker-day-hover-fg | Ink on the hover fill. |
--ki-date-picker-day-radius | Radius of a day and the ends of a range. |
--ki-date-picker-day-size | Default size of a day target. |
--ki-date-picker-fg | Default calendar text. |
--ki-date-picker-field-bg | Fill of the text field. |
--ki-date-picker-field-fg | Text, icon and caret of the field. |
--ki-date-picker-heading-family | Family of the calendar month heading. |
--ki-date-picker-outside-bg | Fill behind dates in neighboring months. |
--ki-date-picker-outside-fg | Ink of dates in neighboring months. |
--ki-date-picker-radius | Calendar popup corner radius. |
--ki-date-picker-range-bg | Fill of the span between selected endpoints. |
--ki-date-picker-range-fg | Text of dates within the span. |
--ki-date-picker-selected-bg | Fill of a chosen day or range endpoint. |
--ki-date-picker-selected-fg | Text of a chosen day or range endpoint. |
--ki-date-picker-shadow | Calendar popup elevation. |
--ki-date-picker-today-border | Outline of the current date. |
--ki-date-picker-weekday-bg | Fill behind weekday names. |
--ki-date-picker-weekday-fg | Ink of weekday names. |
--ki-density-target-min | The 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-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness 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-md | Medium glyph for body content (20px at the default root size). |
--ki-layout-spacing-3xl | The 3xl spacing step for a stack or grid gap. |
--ki-layout-spacing-lg | The lg spacing step for a stack or grid gap. |
--ki-layout-spacing-md | The md spacing step for a stack or grid gap. |
--ki-layout-spacing-xl | The xl spacing step for a stack or grid gap. |
--ki-layout-spacing-xs | The xs spacing step for a stack or grid gap. |
--ki-outline-control | The 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-em | semantic color for outline danger high em. |
--ki-surface-transparent | Transparent surface backing for a background image that carries its own opacity. |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-high-em | semantic color for text high em. |
--ki-text-supporting | Supporting 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-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |