HyCalendar
Usage examples on this page are written for Lit / plain HTML (
<hy-calendar>). The same component ships asHyCalendarin@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
A presentational, keyboard-accessible month grid built on the Temporal API. Pure date engine — no input, no popover. Embeddable standalone (booking surfaces, inline filters) and composed by hy-date-picker.
Selection is single by default; set range for two-endpoint selection. The value is an ISO YYYY-MM-DD (single) or an ISO 8601 interval start/end (range), per DATETIME_COMPONENTS_PLAN.md §3.
Temporal-free first paint
The grid is computed from Temporal, which is awaited via ensureTemporal() on first connect. Before it resolves (and during SSR) the component renders a lightweight loading shell — it never reads Temporal in the constructor or first render, so it passes the @lit-labs/ssr smoke test and behaves on the Safari/no-Temporal path.
Accessibility
role="grid" with a roving tabindex over day buttons; Arrow keys move by day, PageUp/PageDown by month (Shift by year), Home/End to week edges. Today carries aria-current="date"; selected days carry aria-selected. Month changes are announced via a polite live region.
Examples
Single date
<hy-calendar value="2026-03-07"></hy-calendar>Range
<hy-calendar range value="2026-03-07/2026-03-12"></hy-calendar>API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
value | value | string | '' | Selected value — ISO YYYY-MM-DD (single) or ISO interval start/end (range). |
min | min | string | undefined | — | Earliest selectable date (ISO YYYY-MM-DD). Out-of-range days are disabled. |
max | max | string | undefined | — | Latest selectable date (ISO YYYY-MM-DD). Out-of-range days are disabled. |
locale | locale | string | undefined | — | Explicit locale override. Falls back to <html lang> then navigator.language. |
range | range | boolean | false | Enable two-endpoint range selection. |
Events
| Event | Detail | Description |
|---|---|---|
input | — | Fires on each selection step (range anchor, navigation commit). |
change | — | Fires once a selection is committed (single click; range second click). |
CSS Parts
| Part | Description |
|---|---|
base | The calendar wrapper |
header | The month navigation header |
nav-prev | Previous-month button |
nav-next | Next-month button |
heading | The month/year heading |
grid | The day grid |
weekday | A weekday column header |
day | A day button |
live-region | Screen-reader announcement region |
CSS Custom Properties
| Property | Description |
|---|---|
--hy-calendar-cell-size | Edge length of a day cell |
--hy-calendar-gap | Gap between day cells |
--hy-calendar-radius | Corner radius of a day cell |
--hy-calendar-surface-radius | Corner radius of the calendar surface |
--hy-calendar-day-selected-background | Selected day background |
--hy-calendar-day-range-background | In-range day background |
--hy-calendar-day-highlight-foreground | Foreground of in-range and today day cells. Default: var(--hy-foreground-brand-rest). |
--hy-calendar-background | Calendar surface background. Default: var(--hy-background-surface-base). |
--hy-calendar-padding | Padding of the calendar surface. Default: var(--hy-padding-form-md). |
--hy-calendar-day-foreground | Foreground of an in-month day cell. Default: var(--hy-foreground-default-rest). |
--hy-calendar-muted-foreground | Foreground of out-of-month day cells and weekday headers. Default: var(--hy-foreground-subtle-rest). |
--hy-calendar-day-hover-background | Hovered day background. Default: var(--hy-background-neutral-hover). |
--hy-calendar-day-selected-foreground | Selected day foreground. Default: var(--hy-foreground-on-brand-rest). |
--hy-calendar-today-border | Border of the today marker. Default: var(--hy-border-brand-rest). |
--hy-calendar-hover-duration | Hover transition duration. Default: var(--hy-motion-transition-hover-duration). |
--hy-calendar-hover-easing | Hover transition easing. Default: var(--hy-motion-transition-hover-easing). |