TimeField

TimeFields allow users to enter and edit time values using a keyboard. Each part of the time is displayed in an individually editable segment.

Event time

––––AM

label

granularity

size

labelPosition

description

contextualHelp

isDisabled

import {TimeField} from '@react-spectrum/s2';

<TimeField label="Event time" />

Value

Use the value or defaultValue prop to set the time value, using objects in the @internationalized/date package. TimeField accepts plain Time, CalendarDateTime, or ZonedDateTime, but only displays the time.

1145AM

Selected time: 11:45:00

import {Time} from '@internationalized/date';
import {TimeField} from '@react-spectrum/s2';
import {useState} from 'react';

function Example() {
  let [time, setTime] = useState(new Time(11, 45));
  
  return (
    <>
      <TimeField
        value={time}
        onChange={setTime} />
      <p>Selected time: {time ? time.toString() : '--'}</p>
    </>
  );
}

Format options

The time format is automatically determined based on the user's locale. TimeField supports several props to control how values are displayed.

Time

545PMPST

granularity

hourCycle

hideTimeZone

shouldForceLeadingZeros

import {parseZonedDateTime} from '@internationalized/date';
import {TimeField} from '@react-spectrum/s2';

<TimeField
  label="Time"
  defaultValue={parseZonedDateTime('2025-02-03T17:45:00[America/Los_Angeles]')} />

Forms

Use the name prop to submit the selected date to the server as an ISO 8601 string. Set the isRequired, minValue, or maxValue props to validate the value, or implement custom client or server-side validation. See the Forms guide to learn more.

isRequired

necessityIndicator

import {Time} from '@internationalized/date';
import {TimeField, Form, Button} from '@react-spectrum/s2';

function Example(props) {
  return (
    <Form>
      <TimeField
        {...props}
        label="Appointment time"
        name="time"
        isRequired
        minValue={new Time(9)}
        maxValue={new Time(17)}
        validate={time => time?.minute % 15 !== 0 ? 'Appointments start every 15 minutes.' : null}
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

API

Name	Type	Default
`size`	`'S' \| 'M' \| 'L' \| 'XL'`	Default: `'M'`
The size of the TimeField.
`hourCycle`	`12 \| 24`	Default: —
Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`'hour' \| 'minute' \| 'second'`	Default: `'minute'`
Determines the smallest unit that is displayed in the time picker.
`hideTimeZone`	`boolean`	Default: —
Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	Default: —
Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
`placeholderValue`	`TimeValue`	Default: —
A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

`value`	`TimeValue \| null`	Default: —
The current value (controlled).
`defaultValue`	`TimeValue \| null`	Default: —
The default value (uncontrolled).
`onChange`	`(value: MappedTimeValue<TimeValue> \| null) => void`	Default: —
Handler that is called when the value changes.