Time Field

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

Installation

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

npx @tailgrids/cli add time-field

Anatomy

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

export const TimeFieldExample = () => (
  <TimeField>
    <Label>Meeting time</Label>
    <DateInput>{segment => <DateSegment segment={segment} />}</DateInput>
    <Description>Choose a start time for the meeting.</Description>
  </TimeField>
);

Examples

Basic Usage

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

Controlled

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

Uncontrolled

An uncontrolled time field with a defaultValue prop.

With Seconds

Enable second selection by setting the granularity prop to second.

With Timezone

Display and manage time zones within the time field.

With Leading Zeros

Use the shouldForceLeadingZeros prop to display leading zeros in time segments.

Validation

Display error messages and validation states when the time value is invalid.

API Reference

TimeField

The segment-based time input component. Wraps React Aria's TimeField and maps boolean props (disabled, readOnly, required, invalid) to their is-* equivalents.

See the React Aria TimeField documentation for more details.

Composition

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

TimeField                                  — Root container. Manages time state, validation, and ARIA context.
├── Label                                  — Visible label.
├── DateInput (from Date Field)            — Groups editable segments into a styled input area.
│   └── DateSegment (from Date Field)      — Individual editable segment (hour, minute, second, AM/PM).
└── Description                            — Helper text.

• Use TimeField as the root. It provides the time 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 time. 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 time segments (hours, minutes, seconds, AM/PM) 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.