useTimeField

Provides the behavior and accessibility implementation for a time field component. A time field allows users to enter and edit time values using a keyboard. Each part of a time value is displayed in an individually editable segment.

Event time

––––AM

Example

TimeField.tsx

DateField.css

TimeField.css

Form.css

Example

TimeField.tsx

DateField.css

TimeField.css

Form.css

import {TimeField} from './TimeField';

<TimeField label="Event time" />

API

<TimeField>
  <Label />
  <DateInput>
    {segment => <DateSegment segment={segment} />}
  </DateInput>
  <Text slot="description" />
  <FieldError />
</TimeField>

useTimeFieldState<T extends TimeValue = TimeValue>(props: TimeFieldStateOptions<T>): TimeFieldState

useTimeField<T extends TimeValue>(
  props: AriaTimeFieldOptions<T>,
state: TimeFieldState,
ref: RefObject<Element | null>
): DateFieldAria

TimeFieldState

Properties

Name	Type
`timeValue`	`Time`
The current time value.
`dateValue`	`Date`
The current value, converted to a native JavaScript `Date` object.
`calendar`	`Calendar`
The calendar system currently in use.
`segments`	`DateSegment[]`
A list of segments for the current value.
`dateFormatter`	`DateFormatter`
A date formatter configured for the current locale and format.
`granularity`	`Granularity`
The granularity for the field, based on the `granularity` prop and current value.
`maxGranularity`	`'year' \| 'month' \| Granularity`
The maximum date or time unit that is displayed in the field.
`isDisabled`	`boolean`
Whether the field is disabled.
`isReadOnly`	`boolean`
Whether the field is read only.
`realtimeValidation`	`ValidationResult`
Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`
Currently displayed validation results, updated when the user commits their changes.

`value`	`DateValue \| null`
The current field value.
`defaultValue`	`DateValue \| null`
The default field value.

Methods

`setValue(value: DateValue \| null): void`
Sets the field's value.
`increment(type: DateSegmentType): void`
Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrement(type: DateSegmentType): void`
Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementPage(type: DateSegmentType): void`
Increments the given segment by a larger amount, rounding it to the nearest increment. The amount to increment by depends on the field, for example 15 minutes, 7 days, and 5 years. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrementPage(type: DateSegmentType): void`
Decrements the given segment by a larger amount, rounding it to the nearest increment. The amount to decrement by depends on the field, for example 15 minutes, 7 days, and 5 years. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementToMax(type: DateSegmentType): void`
Increments the given segment to its maxiumum value.
`decrementToMin(type: DateSegmentType): void`
Decrements the given segment to its minimum value.
`setSegment(type: DateSegmentType, value: number): void`
Sets the value of the given segment.
`confirmPlaceholder(): void`
Updates the remaining unfilled segments with the placeholder value.
`clearSegment(type: DateSegmentType): void`
Clears the value of the given segment, reverting it to the placeholder.
`formatValue(fieldOptions: FieldOptions): string`
Formats the current date value using the given options.
`getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter`
Gets a formatter based on state's props.
`updateValidation(result: ValidationResult): void`
Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`
Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`
Commits the realtime validation so it is displayed to the user.

AriaTimeFieldProps

Name	Type	Default
`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.

`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.