HyDateField

Usage examples on this page are written for Lit / plain HTML (<hy-date-field>). The same component ships as HyDateField in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A locale-aware segmented date, date-time or time input. Each unit (month / day / year; hour / minute in datetime and time, plus AM/PM on a 12-hour clock) is an arrow-adjustable, type-to-edit spinbutton — the keyboard-first, screen-reader-friendly replacement for a readonly trigger. No calendar; compose with hy-date-picker for the popover.

Independently form-associated — usable standalone with its own name / value and form-control surface (hy-date-picker composes it rather than re-implementing).

Value is ISO YYYY-MM-DD (date), YYYY-MM-DDTHH:MM (datetime) or HH:MM (time), always 24-hour. Segment order, separators and the 12- or 24-hour clock come from the resolved locale via Intl; hour-cycle overrides the clock. On a 12-hour clock the hour arrows cycle within AM or PM and the AM/PM segment switches the period (React Aria's model); A / P set it. min / max compare what the field holds: a date, a full date-time (a date-only bound on a date-time field allows that whole day), or a time.

When to use

• A date people know without looking at a calendar: a birth date, an expiry date.
• A time of day, with type="time".

Do

• Set min and max when only some dates are valid.

When not to use

• A date people choose by looking at a calendar, where the weekday matters: hy-date-picker.
• A start and an end date: hy-date-picker range.
• Showing a date without editing it: the date as text, or hy-relative-time.
• A duration such as 45 minutes: hy-number-input with a suffix.

Accessibility: your part

• When you set min or max, tell people the allowed range. An entry outside it never commits.

Examples

<hy-date-field label="Start date" value="2026-03-07"></hy-date-field>
<hy-date-field type="datetime" label="Starts at"></hy-date-field>
<hy-date-field type="time" label="Opens at" value="09:00"></hy-date-field>
<hy-date-field
  type="time"
  label="Shift start"
  min="06:00"
  max="22:00"
  hour-cycle="24"
></hy-date-field>
<hy-date-field label="Arrival" helper-text="The day you check in."></hy-date-field>
<hy-date-field
  label="Arrival"
  value="2026-03-08"
  warning-message="That is a Sunday: the desk is closed."
></hy-date-field>
<hy-date-field label="Arrival" error-message="Pick a date after today."></hy-date-field>

The line under the field shows the error message, else the warning message, else the helper text. error paints the danger color and sets aria-invalid on the segments; warning paints the warning color at rest and never touches aria-invalid or form validity. Setting a message raises its flag and clearing it lowers it.

API

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	ISO value: YYYY-MM-DD (date), YYYY-MM-DDTHH:MM (datetime) or HH:MM (time), always 24-hour.
type	type	'date' | 'datetime' | 'time'	'date'	date (default), datetime (adds hour and minute) or time (hour and minute only).
hourCycle	hour-cycle	12 | 24	—	12 or 24-hour display for datetime and time. Unset follows the locale (en-US 12, de-CH 24). The value is 24-hour either way.
min	min	string | undefined	—	—
max	max	string | undefined	—	—
locale	locale	string | undefined	—	—
label	label	string	''	—
helperText	helper-text	string	''	Helper text shown under the field while no error or warning message replaces it.
errorMessage	error-message	string	''	Error message shown under the field (replaces the helper text). Setting it raises error.
error	error	boolean	false	Error state: the value is not accepted. Paints the danger color and sets aria-invalid on the segments. Visual and for screen readers only — it never blocks submission.
warningMessage	warning-message	string	''	Warning message shown under the field (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 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 field as required for form validation: while it is empty, checkValidity() is false and native submission is blocked, with the browser's own message on the first segment. The label gets the mark.
name	name	string	''	—
size	size	'small' | 'medium' | 'large'	'medium'	—
width	width	string | undefined	—	—
autofocus	autofocus	boolean	false	—
strings	—	Partial<DateFieldStrings>	{}	The built-in strings — the segments' accessible names, their placeholders, the empty announcement and the AM / PM fallback. Only the keys set replace the English defaults (DEFAULT_DATE_FIELD_STRINGS). Use for internationalization.
form	—	HTMLFormElement | null	—	—
validity	—	ValidityState	—	—

Events

Event	Detail	Description
input	—	Fires on each segment edit that yields a complete valid value.
change	—	Fires on blur / Enter once all segments form a valid value.

CSS Parts

Part	Description
base	Outer wrapper (label, field, message line)
label	The visible label
field	The segmented input row
segment	A single editable segment
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-field-control-height-sm	var(--hy-control-height-sm)	Small-size outer height
--hy-date-field-control-height-md	var(--hy-control-height-md)	Medium-size outer height
--hy-date-field-control-height-lg	var(--hy-control-height-lg)	Large-size outer height
--hy-date-field-foreground-danger-rest	var(--hy-foreground-danger-rest)	Error border, message text and icon color.
--hy-date-field-foreground-warning-rest	var(--hy-foreground-warning-rest)	Warning border (at rest), message text and icon color.
--hy-date-field-gap-layout-2xs	var(--hy-gap-layout-2xs)	Gap between the message icon and its text.