DatePicker

A DateField with a calendar key in its well. Type the date, or open a Calendar under the field and choose it; the flaps turn over to the day you chose. The value is an ISO date.

Feel The field you dial a date into, with a small screen that folds out under it when you'd rather look.

Check-in

Or let the agent fetch it: get_component("date-picker") on the Echo MCP server.

Installation

npx echo-ui-cli add date-picker

First time? Run npx echo-ui-cli init once — it sets the project up, and add refuses to run before it.

At a glance

Version: 0.3.0
Weight: 7.8 KB · 77.5 KB with what it imports · 4.5 KB of CSS (minified and gzipped; React not counted)
Needs: date-field (Echo, brought with it), calendar (Echo, brought with it), popover (Echo, brought with it), hardware-button (Echo, brought with it)
Keyboard: The calendar key is a named button (calendarLabel), and Alt+↓ on a wheel opens the calendar too.
The calendar opens with focus on the chosen day, or today. Enter chooses and closes it; Escape closes it without choosing. Focus goes back to the key.
Reduced motion: The popup fades instead of growing, the month doesn't slide, and the flaps don't turn.
Sound: The popup's select click as it opens, the calendar's as a day is chosen, and the flaps' tick as they turn, inside a SoundProvider.

Usage

tsx

import { DatePicker } from "@/echo/date-picker";

<DatePicker label="Date" value={date} onValueChange={setDate} />

Composition

DatePicker → DateField (the wheels) + a HardwareButton key in its well → Popover → Calendar

Examples

A date, typed or chosen

The key opens the calendar; choosing a day closes it.

tsx

<DatePicker label="Due" value={due} onValueChange={setDue} />

With limits

The field says a date outside them in words, and the calendar won't page past them.

tsx

<DatePicker
  label="Check-in"
  min="2026-10-01"
  max="2026-12-31"
  unavailable={(iso) => booked.includes(iso)}
  value={checkIn}
  onValueChange={setCheckIn}
/>

Accessibility

The field is DateField, with its wheels and keys; the calendar is Calendar, with its grid and keys.
The calendar key is a named button (calendarLabel), and Alt+↓ on a wheel opens the calendar too.
The calendar opens with focus on the chosen day, or today. Enter chooses and closes it; Escape closes it without choosing. Focus goes back to the key.
The popup is named by calendarLabel, so a screen reader says what opened.

Tested against WCAG 2.2 AA on every release:

axe — No axe violations, in the component's own gallery and on its page.
keyboard — Every action is reachable and operable from the keyboard alone.
focus-visible — Focus is visible on every focusable part, in normal and forced-colors mode.
forced-colors — State stays visible when the look's colours are replaced by the system's.
target-size — Every target's real hit area is at least 24×24px, at every density.
reflow — Content reflows into 320px and survives a doubled text size.

Not covered: screen-reader: not yet verified by a person. Everything above is a machine check; a person has not yet driven this component with a screen reader.

Motion & sound

Motion tokens: --echo-duration-swap
Reduced motion: The popup fades instead of growing, the month doesn't slide, and the flaps don't turn.
Sound: The popup's select click as it opens, the calendar's as a day is chosen, and the flaps' tick as they turn, inside a SoundProvider.

Props

DatePicker props
Prop	Type	Default
`id`The element's id, so a <label for> or an aria-describedby can reach it.	`string`
`name`The field's name in a form submission, and the key react-hook-form registers.	`string`
`disabled`	`boolean`
`required`	`boolean`
`readOnly`	`boolean`
`autoFocus`Focus this control when it mounts. One per page, at most.	`boolean`
`onBlur`Fired on focus loss. react-hook-form validates onTouched and onBlur with it.	`function`
`onFocus`Fired when the control takes focus.	`function`
`onKeyDown`Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's.	`function`
`label`Visible eyebrow label; also the name every wheel says before its own. A date field needs label, aria-label or aria-labelledby: leaving all three out is a type error.	`string`
`value`Controlled value, an ISO date ("2026-09-28"), or "" for none.	`string`
`defaultValue`Uncontrolled initial value, an ISO date.	`string`
`onValueChange`Fired with the ISO date once the wheels make a real one, and with "" when they stop making one.	`function`
`min`The earliest date, as ISO. The year wheel starts at its year; an earlier date is said to be, in words, under the field.	`string`
`max`The latest date, as ISO. The year wheel ends at its year.	`string`
`unavailable`Asked with each ISO date: true for one that can't be chosen (a weekend, a booked day). The field says so under it.	`function`
`locale`Whose order and names, as a BCP 47 tag ("en-GB", "de"). Default: the browser's. Pass it from the request on a server-rendered page, so the first paint is already in the right order.	`string`
`size`Height on the control scale: sm 32px, md 44px, lg 60px, the same as a Field beside it. Defaults to the nearest SizeProvider's size.	`"sm" \| "md" \| "lg"`	`"md"`
`description`Help text under the field, linked to it so a screen reader reads it after the name.	`unknown`
`error`What's wrong, in words. While set, the field is invalid, and it wins over the field's own min, max and unavailable messages.	`string`
`aria-label`Used only when `label` is omitted; a visible label wins.	`string`
`aria-labelledby`Used only when `label` is omitted.	`string`
`aria-describedby`Ids of other text that describes the field, read after its own description and error.	`string`
`firstDayOfWeek`The week's first day on the calendar, 0 for Sunday to 6 for Saturday. Default: the locale's.	`number`
`calendarLabel`The calendar key's name, and the popup's. Default "Choose from a calendar".	`string`

Anti-patterns

Don't use it for a date that's always typed (a birthday nobody finds on a grid): DateField alone is quicker.
Don't use two for a range: a date range picker is coming soon.

Changelog

v0.3.0 · 2026-10-12 · ChangedEvery item needs echo-ui-core 0.3.0 (all components). The drawn device, readability past AA and the design tests live in core, and the components that use them are built against it, so each item now declares echo-ui-core >=0.3.0 <0.4.0. Update core with the items: npm install echo-ui-core@^0.3.0 (or your package manager's), then npx echo-ui-cli update. An item whose files didn't change is the same code under a new version; the 0.2.0 files stay published.
v0.2.0 · 2026-10-04 · AddedDates: DateField, Calendar and DatePicker (echo-date-field, echo-calendar, echo-date-picker). DateField types a date into wheels, day, month and year in the order the locale writes them, each a row of small flaps that turn over to the value, in Field's well and on its size scale: type the digits and a wheel moves on by itself, or step it with the arrows. On a phone it opens the numeric keyboard, and a pasted ISO date fills every wheel. Calendar is a month on a device screen: one Tab stop, the calendar keys (arrows, Home and End, Page Up and Page Down), the chosen day lit, today on a lit rail, and days that can't be chosen struck through. DatePicker is the two together: a calendar key in the field's well (or Alt+↓ on a wheel) opens the Calendar under it, and choosing a day closes it and turns the flaps. All three take min, max and unavailable, write the value as an ISO date (2026-09-28) so no time zone moves a day, follow the locale's order, names, digits and first weekday (Arabic runs right to left, Hebrew left to right), and put the date in a form with name. A date outside the limits is said in words under the field.
v0.2.0 · 2026-10-04 · ChangedComments only, no behaviour change. Comments in the component source used to cite documents, milestones and ticket numbers from Echo's own planning, none of which exist in your project. The citations are gone and the sentences around them stay. Where a comment was only a citation, it now says what it meant. Three development warnings (HardwareButton's engraved/caption checks and StatusDot's missing-label check) also dropped the ticket code at the end of the message. echo-ui diff will show changes in most items; none of them are to code.
v0.2.0 · 2026-10-04 · ChangedAn item's version is now a function of declared data, not of how the changelog is formatted. The version an item ships under is published once and never rewritten, and it used to be inferred from prose: a regex for a bolded "Breaking" run across the whole unreleased section, and attribution by "does a bullet mention this name in backticks". One breaking entry therefore moved every item that changed that cycle, and an entry explaining that "Menu and Sheet are unchanged here" filed itself as a change to Menu and Sheet — which it really had.
v0.2.0 · 2026-10-04 · ChangedThe agent brief says Echo has not shipped. llms.txt and the MCP server's instructions led with npx echo-ui-cli init, and that name on npm is a reserved stub with no executable — so a model following the brief wrote an install step that fails with npx's own error. The brief now opens with the caveat, and the docs carry it on every surface that shows a command. One switch (CLI_RELEASED) silences all of them at launch, and a test refuses to let one move without the others. Affects all components only in what the brief says about installing them; no item's props, CSS or rendered semantics change.
v0.2.0 · 2026-10-04 · ChangedEcho's home is echo-ui.com. The registry, the docs and the packages all move to it from echo.nawwara.studio. Nothing was published under the old host, so no echo.json anywhere points at it and there is nothing to migrate — this is the last release where that is true.
v0.2.0 · 2026-10-04 · ChangedWeights, line heights, letter-spacing, z-index, border widths and icon sizes come from the theme scales in all components, with the old value as a fallback, so components keep working with echo-ui-core@0.0.1. Strays moved to the nearest step: most by under a pixel; HardwareButton icons are 14/16/20px (were 15/17/19).
v0.2.0 · 2026-10-04 · FixedContent now reflows into a 320px screen (400% zoom) and survives a doubled browser text size (WCAG 1.4.10, 1.4.4), across all components. Select's 180px floor, NumberField's readout, Segmented and Steps as flex items, EmptyState's grid columns, and Avatar's fixed-pixel disc all gave way; Panel counts its padding inside a width you set (box-sizing: border-box), so a <Panel style={{ width: 220 }}> is now 220px wide overall rather than 260px.

Preview