Date Picker
Form-associated date input wrapping the native calendar UI. A Lit Web Component migrated from the Angular esa-date-picker.
Preview
<esa-date-picker label="Event date" help-text="Pick any day"></esa-date-picker>import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-date-picker';
@Component({
selector: 'app-date-picker-demo',
standalone: true,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<esa-date-picker label="Event date" help-text="Pick any day"></esa-date-picker>
`,
})
export class DatePickerDemo {}Sizes
<esa-date-picker label="Extra small" size="xs"></esa-date-picker>
<esa-date-picker label="Small" size="sm"></esa-date-picker>
<esa-date-picker label="Medium" size="md"></esa-date-picker>
<esa-date-picker label="Large" size="lg"></esa-date-picker>import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-date-picker';
@Component({
selector: 'app-date-picker-demo',
standalone: true,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<esa-date-picker label="Extra small" size="xs"></esa-date-picker>
<esa-date-picker label="Small" size="sm"></esa-date-picker>
<esa-date-picker label="Medium" size="md"></esa-date-picker>
<esa-date-picker label="Large" size="lg"></esa-date-picker>
`,
})
export class DatePickerDemo {}States
Constrain selectable days with min/max. Preset, required, error, and disabled states are attribute-driven.
<esa-date-picker label="Within 2026" min="2026-01-01" max="2026-12-31"></esa-date-picker>
<esa-date-picker label="Preset value" value="2026-06-03"></esa-date-picker>
<esa-date-picker label="Required" required></esa-date-picker>
<esa-date-picker label="Error" error-text="Date is required"></esa-date-picker>
<esa-date-picker label="Disabled" disabled value="2026-06-03"></esa-date-picker>import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-date-picker';
@Component({
selector: 'app-date-picker-demo',
standalone: true,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<esa-date-picker label="Within 2026" min="2026-01-01" max="2026-12-31"></esa-date-picker>
<esa-date-picker label="Preset value" value="2026-06-03"></esa-date-picker>
<esa-date-picker label="Required" required></esa-date-picker>
<esa-date-picker label="Error" error-text="Date is required"></esa-date-picker>
<esa-date-picker label="Disabled" disabled value="2026-06-03"></esa-date-picker>
`,
})
export class DatePickerDemo {}API
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | '' | Field label above the input. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Control size (reflected attribute). |
placeholder | string | 'Select date...' | Placeholder text. |
min | string | '' | Earliest selectable date (YYYY-MM-DD). |
max | string | '' | Latest selectable date (YYYY-MM-DD). |
disabled | boolean | false | Disables interaction (reflected attribute). |
name | string | undefined | — | Form field name — the key this control submits under. |
help-text | string | '' | Helper text below the input. Property: `helpText`. |
error-text | string | '' | Error message; sets the error state when present. Property: `errorText`. |
required | boolean | false | Marks the field required (renders a * after the label). |
live-error | boolean | false | Announce the error the moment it appears rather than only when the field is focused. OFF by default — see the long note on `esa-text-field.liveError`: the house pattern is validate-on-submit with `<esa-error-summary>`, under which a live region per field fires an assertive announcement for EVERY invalid field at once, racing the summary the user was just sent to. Turn it on for fields validated INLINE, on blur. Property: `liveError`. |
value | string | '' | ISO date value (YYYY-MM-DD). |
Events
| Event | Type | Default | Description |
|---|---|---|---|
change | CustomEvent<{ value: string }> | — | Fired on input. Value is an ISO YYYY-MM-DD string. Composed and bubbles. |
Binding these events from Angular
Every one of these is a CustomEvent, so the payload is on
$event.detail — $event.target.value reads empty, with no
error. The names are lowercase and Angular passes them to
addEventListener verbatim, so camel-casing one means it never fires.
(change)="onChange($event.detail)"
Accessibility
- Renders a native
<input type="date">— the browser supplies the calendar and full keyboard handling. - The input is labelled via
aria-label(falls back to "Date" when no label is set). min/maxmap to native input bounds, blocking out-of-range selection.- Form-associated via
ElementInternals— value submits with the enclosing form.
Theming surface
Every public token this component reads, extracted from its source at build time,
split by blast radius: the hooks that belong to this component,
then the shared and system tokens it consumes alongside everything else. The
Resolves to column walks each token's real lineage —
component → semantic → primitive → raw value — so you
can see exactly where re-pointing it lands. A spoke re-skins by overriding these in
its theme-<slug>.css; component internals are never edited. No
hook for what you need? File it with /request-lego.
Type roles it names
This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.
| Role | Re-point | Reach |
|---|---|---|
.typography-body-sm |
| +20 more componentsesa-alert-box, esa-breadcrumbs, esa-button-toggle, esa-card, esa-checkbox-group, esa-combobox, esa-command-palette, esa-empty-state, esa-file-upload, esa-form-field, esa-input-tag, esa-link-column, esa-loading-overlay, esa-progress-bar, esa-radio-group, esa-search-panel, esa-select, esa-stat, esa-text-field, esa-textarea |
.typography-label-2xs |
| +11 more componentsesa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-form-field, esa-input-tag, esa-progress-bar, esa-radio-group, esa-range-slider, esa-text-field, esa-textarea |
.typography-label-lg |
| +12 more componentsesa-breadcrumbs, esa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-form-field, esa-input-tag, esa-radio-group, esa-range-slider, esa-select, esa-text-field, esa-textarea |
.typography-label-md |
| +33 more componentsesa-app-bar, esa-breadcrumbs, esa-button-group, esa-button-toggle, esa-card, esa-checkbox-group, esa-color-picker, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-danger-zone, esa-dialog, esa-empty-state, esa-entity-search, esa-file-upload, esa-filter-container, esa-form-field, esa-header-nav, esa-input-tag, esa-link-column, esa-page-header, esa-pillbox, esa-popover, esa-progress-bar, esa-radio-group, esa-range-slider, esa-select, esa-side-dialog, esa-sidebar-nav, esa-stat, esa-text-field, esa-textarea, esa-tooltip |
.typography-label-xs |
| +14 more componentsesa-breadcrumbs, esa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-entity-search, esa-form-field, esa-input-tag, esa-progress-bar, esa-radio-group, esa-range-slider, esa-select, esa-text-field, esa-textarea |
.typography-microcopy-2xs-subtle |
| +3 more componentsesa-combobox, esa-input-tag, esa-text-field |
.typography-microcopy-lg-subtle |
| +7 more componentsesa-combobox, esa-command-palette, esa-entity-search, esa-filter-dropdown, esa-input-tag, esa-select, esa-text-field |
.typography-microcopy-md-subtle |
| +7 more componentsesa-combobox, esa-filter-dropdown, esa-input-tag, esa-pagination, esa-search-panel, esa-select, esa-text-field |
.typography-microcopy-xs-subtle |
| +7 more componentsesa-combobox, esa-filter-dropdown, esa-filter-pills, esa-input-tag, esa-select, esa-text-field, esa-tooltip |
Wired to this component
None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.
Shared tokens it reads
Owned by a family or by the semantic layer. Still overridable — but scope the
override (esa-foo { --form-border-color: … }) unless you mean to move
everything that reads it. Reach says what else that is.
| Token | Reach | Resolves to |
|---|---|---|
--focus-ring-color | component focus ring group · +34 more | #3e9b4f via --color-border-default-focus → --color-grass-10 |
--focus-ring-offset | component focus ring group · +31 more | 2px |
--focus-ring-width | component focus ring group · +35 more | 2px via --border-width-focus → --border-width-200 |
--form-border-color | component forms group · +11 more | one role per property, so a theme can move the ring's weight and its colour independently. Tier 3's --focus-ring-width now reads this instead of holding a bare 2px, which is the same shape --focus-ring-color has always had (a thin tier-3 alias over a tier-2 role) — width was simply never given the tier-2 half.
*
* This role was rejected once, and the rejection is worth recording because its PREMISE was wrong rather than its reasoning. The argument against an `emphasis` width was that every 2px border in the kit is micro-geometry — spinner rings, the kbd keycap lip, a chevron. The focus ring was not in that enumeration and does not fit it: 33 components render it, more than read any other tier-3 token, and it is not micro-geometry but an accessibility affordance whose weight is a legitimate brand axis (a spoke that needs a heavier ring for contrast has to be able to reach it). It is also not a `border` in any component — every consumer paints it with `outline` or `box-shadow` — which is precisely why a survey of BORDERS missed it. The name still says `border` because tier 2 already calls the ring's colour --color-border-default-focus via --color-border-default |
--form-border-color-focus | component forms group · +11 more | #3e9b4f via --color-border-default-focus → --color-grass-10 |
--form-border-width | component forms group · +10 more | 1px via --border-width-default → --border-width-100 |
--form-error-border-color | component forms group · +9 more | #ce2c31 via --color-background-utility-danger → --color-red-11 |
--form-error-color | component forms group · +9 more | #ce2c31 via --color-content-utility-danger → --color-red-11 |
--form-help-color | component forms group · +9 more | #646464 via --color-content-default-secondary → --color-gray-11 |
--form-label-color | component forms group · +7 more | #646464 via --color-content-default-secondary → --color-gray-11 |
--form-text-color | component forms group · +6 more | #202020 via --color-content-default → --color-gray-12 |
--color-background-disabled | semantic every component | #f0f0f0 via --color-gray-3 |
--color-background-field | semantic every component | rgba(0, 0, 0, 0) |
--color-border-disabled | semantic every component | #d9d9d9 via --color-gray-6 |
--color-content-disabled | semantic every component | #8d8d8d via --color-gray-9 |
--color-content-utility-danger | semantic every component | #ce2c31 via --color-red-11 |
--radius-md | semantic every component | 0.5rem via --radius-200 |
--radius-sm | semantic every component | 0.25rem via --radius-100 |
--transition-fast | semantic every component | 150ms via --duration-150 |
--spacing-100 | primitive every component | 0.25rem |
--spacing-200 | primitive every component | 0.5rem |
--spacing-250 | primitive every component | 0.625rem |
--spacing-300 | primitive every component | 0.75rem |
--spacing-400 | primitive every component | 1rem |