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 — see DATETIME_COMPONENTS_PLAN.md §3.
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>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 | '' | — |
helpText | help-text | string | '' | — |
errorMessage | error-message | string | '' | — |
invalid | invalid | boolean | false | — |
disabled | disabled | boolean | false | — |
name | name | string | '' | — |
size | size | 'small' | 'medium' | 'large' | 'medium' | — |
width | width | string | undefined | — | — |
autofocus | autofocus | boolean | false | — |
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 trigger row (field(s) + calendar button) |
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 | Error message when invalid |
CSS Custom Properties
| Property | Description |
|---|---|
--hy-date-picker-gap | Gap between the fields and calendar button |