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.

Meeting time

Choose a start time for the meeting.

Installation

The Time Field relies on the react-aria-components and react-stately libraries.

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add time-field

Anatomy

import {
  TimeField,
  TimeFieldInput,
  TimeFieldLabel,
  TimeFieldDescription,
  TimeFieldError
} from "@/components/tailgrids/core/time-field";

export const TimeFieldExample = () => (
  <TimeField label="Meeting time">
    <TimeFieldLabel />
    <TimeFieldInput />
    <TimeFieldDescription />
    <TimeFieldError />
  </TimeField>
);

Examples

Basic Usage

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

Meeting time

––

Choose a start time for the meeting.

Controlled

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

Meeting time

Uncontrolled

An uncontrolled time field with a defaultValue prop.

Meeting time

With Seconds

Enable second selection by setting the granularity prop to second.

Precise Time

With Timezone

Display and manage time zones within the time field.

UTC Event

Validation

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

Meeting time

––

Business hours only

Must be between 9 AM and 5 PM

API Reference

TimeField

The segment-based time input component.

Prop	Type	Default	Description
`value`	`TimeValue`	-	The current value (controlled).
`defaultValue`	`TimeValue`	-	The default value (uncontrolled).
`onChange`	`(value: TimeValue) => void`	-	Handler that is called when the value changes.
`label`	`string`	-	The content to display as the label.
`description`	`string`	-	The content to display as the description.
`errorMessage`	`string \| ((v: ValidationResult) => string)`	-	The content to display as the error message.
`hourCycle`	`12 \| 24`	-	Whether to use 12 or 24 hour cycle.
`granularity`	`'hour' \| 'minute' \| 'second'`	`'minute'`	The smallest unit of time to display.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`minValue`	`TimeValue`	-	The minimum allowed time.
`maxValue`	`TimeValue`	-	The maximum allowed time.
`disabled`	`boolean`	`false`	Whether the input is disabled.
`readOnly`	`boolean`	`false`	Whether the input is read only.
`required`	`boolean`	`false`	Whether the input is required.
`invalid`	`boolean`	`false`	Whether the input is shown in invalid state.
`className`	`string`	-	Additional CSS classes to apply to the container.

TimeFieldLabel

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the label.

TimeFieldInput

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the input container.

TimeFieldDescription

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the description.

TimeFieldError

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the error message.

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.

Time Field

CLI

Manual

On this page