DateField

Anatomy

A <DateField> is a wrapper around three segments (month, day, year) that the user navigates with arrow keys. Each segment is keyboard-driven and never opens a popover — for a popover calendar, use <DatePicker>.

<DateField label="Birthday" />
<DateField label="Joined" defaultValue={today(getLocalTimeZone())} />
<DateField label="Renewal" minValue={today(getLocalTimeZone())} tone="brand" />

When to use

• A single date that doesn’t need a calendar picker (birthday, due date, appointment).
• Inside larger forms where opening a popover would feel heavy.

When to reach for <DatePicker> instead

• Users need to scan a month at a glance.
• The valid date range is small and visualizing it as a grid helps.

Examples

Controlled with react-aria-components date utilities

import { parseDate, type DateValue } from '@internationalized/date';
import { DateField } from '@helixui/core';

const [value, setValue] = useState<DateValue | null>(parseDate('2026-05-25'));

<DateField label="Renewal" value={value} onChange={setValue} />

Validation

<DateField
  label="Departure"
  isInvalid={isPast(departure)}
  errorMessage="Departure must be in the future."
  tone="danger"
/>

Install: @helixui/core

import { DateField } from '@helixui/core'

status: stable · since: 0.1.0

Tags: date, input, segmented, picker, calendar

Props

Name	Type	Default	Description
label	string	undefined	Field label rendered above the segmented input.
description	string	undefined	Helper text rendered below the field.
errorMessage	string	undefined	Validation message shown when the field is invalid.
tone	'brand' | 'neutral' | 'danger'	brand	Tone for the focus ring and error styling.
size	'sm' | 'md' | 'lg'	md	Touch target size, matching every other helixui input.
value	DateValue | null	undefined	Controlled value.
defaultValue	DateValue	undefined	Uncontrolled initial value.
onChange	(value: DateValue | null) => void	undefined	Fires whenever the user completes a segment edit.
minValue	DateValue	undefined	Earliest selectable date.
maxValue	DateValue	undefined	Latest selectable date.
isDisabled	boolean	false	Renders the field disabled and removes it from tab order.
isReadOnly	boolean	false	Renders the field non-editable but still focusable.

Tokens used

color.bg.input, color.bg.surface.default, color.border.subtle, color.border.action.brand, color.border.danger, color.text.primary, color.text.secondary, color.text.muted, color.text.action.brand, color.text.danger, radius.sm, radius.md, spacing.1, spacing.2, spacing.3, spacing.4, font.size.sm, font.size.md, font.size.lg, font.size.xs

Accessibility

Role: group

Keyboard

Key	Action
Tab	Focus the next segment.
ArrowUp	Increment the focused segment.
ArrowDown	Decrement the focused segment.
0-9	Overwrite the focused segment.

Notes

• Each segment is independently focusable.
• Disabled and read-only states respect ARIA conventions.
• errorMessage is announced via aria-describedby.