DateField

React Date Field components allow users to select a specific date value using a segment-based input. They are commonly used in booking forms, event scheduling, date filters, and registration flows where precise keyboard entry is preferred.

Installation

The Date Field relies on the react-aria-components library.

npx @tailgrids/cli add date-field

Anatomy

import { Label } from "@/components/tailgrids/core/label";
import { Description } from "@/components/tailgrids/core/description";
import { DateField } from "@/components/tailgrids/core/date-field";
import { DateInput, DateSegment } from "@/components/tailgrids/core/date-field";

export const DateFieldExample = () => (
  <DateField>
    <Label>Appointment date</Label>
    <DateInput>{segment => <DateSegment segment={segment} />}</DateInput>
    <Description>Select your preferred appointment date.</Description>
  </DateField>
);

Examples

Basic Usage

A standard date field implementation using segments for precise date entry.

Controlled

Manage the date value externally using the value and onChange props.

Uncontrolled

An uncontrolled date field with a defaultValue prop.

Disabled

A disabled date field prevents user interaction.

Validation

Display error messages and validation states when the date value is outside the allowed range.

With Date and Time

Combine date and time by using a CalendarDateTime value. Set granularity to "minute" to expose time segments.

With Min / Max

Constrain the selectable date range using minValue and maxValue.

With Leading Zeros

Use the shouldForceLeadingZeros prop to display leading zeros in day and month segments.

International Calendar

Wrap the DateField with an I18nProvider and set the locale prop to use a different calendar system.

API Reference

DateField

The field container that provides context for the date input and segments. Manages state, validation, and ARIA attributes.

DateInput

The styled input container that wraps date segments. Supports visual state variants for form feedback.

DateSegment

An individual editable segment of the date (day, month, year, hour, etc.).

See the React Aria DateField documentation for more details.

Composition

The Date Field is composed of the root DateField component plus DateInput and DateSegment. It can be combined with shared field components (Label, Description, FieldError) for a complete form control.

DateField                                — Root container. Manages date state, validation, and ARIA context.
├── Label                                — Visible label.
├── DateInput                            — Groups editable segments into a styled input area.
│   └── DateSegment                      — Individual editable segment (day, month, year, hour, minute).
└── Description                          — Helper text.

• Use DateField as the root. It provides the date value, validation state, and keyboard context to all children.
• Use Label to label the field. It is automatically linked to the input.
• Use DateInput to render the segment group. It accepts a render function that receives each segment and returns a DateSegment.
• Use DateSegment inside DateInput to render each editable part of the date. It handles focus, typing, and arrow-key incrementing.
• Use Description for helper text. It is automatically announced by screen readers.
• Use FieldError for validation messages. It is linked via aria-errormessage when invalid is set.

Accessibility

• Keyboard Support: Users can navigate between date segments (day, month, year) using Arrow keys and edit values using the number keys.
• Screen Readers: Each segment is properly labeled and provides live updates to screen readers as values change.
• Focus Management: Focus is managed automatically between segments for a seamless typing experience.