HyDatePicker
Usage examples on this page are written for Lit / plain HTML (
<hy-date-picker>). The same component ships asHyDatePickerin@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
The full date form control: an editable hy-date-field (segmented input) plus an hy-popover-hosted hy-calendar. Mirrors hy-color-picker's form-associated host + popover + custom interior architecture.
type="datetime" enables the field's time segments; range switches to two fields + a range calendar. Value is a single ISO YYYY-MM-DD[THH:MM] or, in range mode, an ISO 8601 interval start/end. On form submit the JS value is projected to two scalar fields ({name}.start / {name}.end) in range mode.
The calendar button alone opens and closes the calendar (it carries aria-haspopup="dialog" and aria-expanded); the date segments are for typing and never toggle it. The popover is positioned against the whole row (the popover's anchor), and a click in the row does not dismiss it.
When to use
- A date near today that people choose by looking at the week: a due date, a delivery date, a meeting.
- A start and an end date, with
range.
Do
- Set
minandmaxso dates outside them cannot be picked.
When not to use
- A date far from today, such as a birth date:
hy-date-fieldon its own. - A time of day:
hy-date-field type="time". - A calendar that stays visible, such as a booking surface or inline filter:
hy-calendar. - Showing a date rather than choosing one: the date as text, or
hy-relative-time.
Accessibility: your part
- Set
label, oraria-label/aria-labelledbyon the host when the surrounding context already names it; the name covers both the field and the calendar dialog.
Examples
<hy-date-picker label="Date" value="2026-03-07"></hy-date-picker>
<hy-date-picker label="Stay" range value="2026-03-07/2026-03-10"></hy-date-picker>
<hy-date-picker label="Arrival" helper-text="The day you check in."></hy-date-picker>
<hy-date-picker
label="Arrival"
value="2026-03-08"
warning-message="That is a Sunday: the desk is closed."
></hy-date-picker>
<hy-date-picker label="Arrival" error-message="Pick a date after today."></hy-date-picker>One line shows under the control: the error message, else the warning message, else the helper text. The picker forwards error and warning to its field(s), which paint the state (and, for error, set aria-invalid on their segments); the message line is the picker's own, one for both fields in range mode. A warning never touches aria-invalid or form validity.
API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
value | value | string | '' | Selected value — ISO YYYY-MM-DD[THH:MM], or ISO interval start/end in range mode. |
type | type | 'date' | 'datetime' | 'date' | date (default) or datetime (adds a time segment to the field). |
range | range | boolean | false | Range selection — one interval value, two form fields, one popover. |
min | min | string | undefined | — | — |
max | max | string | undefined | — | — |
locale | locale | string | undefined | — | — |
placement | placement | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'bottom-start' | — |
open | open | boolean | false | — |
label | label | string | '' | — |
helperText | helper-text | string | '' | Helper text shown under the control while no error or warning message replaces it. |
errorMessage | error-message | string | '' | Error message shown under the control (replaces the helper text). Setting it raises error. |
error | error | boolean | false | Error state: the value is not accepted. Paints the danger color on the field(s) and sets aria-invalid on their segments. Visual and for screen readers only — it never blocks submission. |
warningMessage | warning-message | string | '' | Warning message shown under the control (replaces the helper text). Setting it raises warning. |
warning | warning | boolean | false | Warning state: the value is accepted but worth a second look. Paints the warning color on the field(s) at rest and shows warning-message; never sets aria-invalid and never blocks submission. error wins when both are set. |
disabled | disabled | boolean | false | — |
required | required | boolean | false | Marks the picker as required: passed to its field(s), and while the value is empty checkValidity() is false and native submission is blocked. |
name | name | string | '' | — |
size | size | 'small' | 'medium' | 'large' | 'medium' | — |
width | width | string | undefined | — | — |
autofocus | autofocus | boolean | false | — |
strings | — | Partial<DatePickerStrings> | {} | The built-in strings — the picker's own (the range fields' names, the calendar button, the popover's fallback name, the Today and Clear shortcuts) and those of the calendar and date field(s) it renders, which it forwards to them. Only the keys set replace the English defaults (DEFAULT_DATE_PICKER_STRINGS). Use for internationalization. |
form | — | HTMLFormElement | null | — | — |
validity | — | ValidityState | — | — |
Events
| Event | Detail | Description |
|---|---|---|
input | — | Fires on each calendar/field selection. |
change | — | Fires once the value is committed. |
CSS Parts
| Part | Description |
|---|---|
base | Outer wrapper |
label | The visible label |
control | The control row (field(s) + calendar button) — the popover's anchor |
calendar-button | The calendar-toggle button |
surface | The popover surface |
shortcuts | The shortcut row (Today / Clear) inside the surface |
shortcut-today | The Today shortcut button |
shortcut-clear | The Clear shortcut button |
helper-text | Helper text |
error-message | The error message element |
warning-message | The warning message element |
message-icon | The icon starting the error or warning message |
CSS Custom Properties
The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.
| Property | Default | Description |
|---|---|---|
--hy-date-picker-gap-form-sm | var(--hy-gap-form-sm) | Gap between the fields and calendar button |
--hy-date-picker-foreground-danger-rest | var(--hy-foreground-danger-rest) | Error message text and icon color. |
--hy-date-picker-foreground-warning-rest | var(--hy-foreground-warning-rest) | Warning message text and icon color. |
--hy-date-picker-gap-layout-2xs | var(--hy-gap-layout-2xs) | Gap between the message icon and its text. |