1. Components
  2. Dates
  3. Time Field

Time Field

TimeFields allow users to enter and edit time values using a keyboard.

Aria docsAria API ReferenceReport an issueEdit this page
<TimeField />

Installation

npx dotui-cli@latest add time-field

Usage

Use a TimeField to allow users to enter and edit time values using a keyboard.

Options

Label

A visual label can be provided for the TimeField using the label prop or a hidden label using aria-label prop.

Event time
<TimeField label="Event time" />
<TimeField aria-label="Event time" />

Sizes

Use the size prop to control the size of the TimeField.
The default variant is "md".

small (sm)
medium (md)
large (lg)
<TimeField size="sm" />
<TimeField size="md" />
<TimeField size="lg" />

Prefix and suffix

To add additional context for the TimeField, such as an icon, use the prefix and suffix props.

<TimeField prefix={<TimerIcon />} />
<TimeField suffix={<TimerIcon />} />

Description

A description can be supplied to TimeField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

AppointmentPlease select a time between 9 AM and 5 PM.
<TimeField label="Appointment" description="Please select a time between 9 AM and 5 PM." />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a TimeField.

Appointment
<TimeField
  label="Appointment"
  contextualHelp={<ContextualHelp />  }
/>

Error message

An errorMessage can be supplied to TimeField via the errorMessage prop, which will be displayed when the isInvalid prop is set to true.

MeetingMeetings start every 15 minutes.
<TimeField label="Meeting" isInvalid errorMessage="Meetings start every 15 minutes." />

Time zones

TimeField is time zone aware when a ZonedDateTime object is provided as the value.

<TimeField defaultValue={parseAbsoluteToLocal("2021-11-07T07:45:00Z")} />

Granularity

The granularity prop allows you to control the smallest unit that is displayed by TimeField.

<TimeField granularity="second" defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")} />

Placeholder value

Use the placeholderValue prop to control the default values of each segment. The default value is midnight.

<TimeField placeholderValue={new Time(9)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

<TimeField
  defaultValue={parseZonedDateTime("2022-11-07T10:45[America/Los_Angeles]")}
  hideTimeZone
/>

Hour cycle

Use the hourCycle prop to control the hour cycle of the TimeField.

<TimeField hourCycle={24} />

Loading

Use the isLoading prop to control the loading state of the TimeField. Use the loaderPosition prop to control the position of the loader.

<TimeField isLoading loaderPosition="prefix" />
<TimeField isLoading loaderPosition="suffix" />

Disabled

Use the isDisabled prop to disable the TimeField.

Event time
<TimeField label="Event time" isDisabled />

ReadOnly

The isReadOnly boolean prop makes the TimeField's text content immutable. Unlike isDisabled, the TimeField remains focusable and the contents can still be copied.

Event time
<TimeField label="Event time" value={new Time(11)} isReadOnly />

Required

Use the isRequired prop to mark the TimeField as required. Use the necessityIndicator prop to control the visual style of the required state.

Event time
Event time ​
Event time ​
Event time ​
<TimeField label="Event time" isRequired />
<TimeField label="Event time" isRequired necessityIndicator="icon" />
<TimeField label="Event time" isRequired necessityIndicator="label" />
<TimeField label="Event time" necessityIndicator="label" />

Uncontrolled

An initial, uncontrolled value can be provided to the TimeField using the defaultValue prop.

<TimeField defaultValue={new Time(11, 45)} />

Controlled

Use the value and onChange props to control the value of the input.

selected time: 11:45:00

const [time, setTime] = React.useState(new Time(11, 45));
return <TimeField value={time} onChange={setTime} />

Composition

If you need to customize things further, you can drop down to the composition level.

Meeting timePlease select a time between 9 AM and 5 PM.
<TimeFieldRoot>
  <Label>Meeting time</Label>
  <InputRoot>
    <DateInput>{(segment) => <DateSegment segment={segment} />}</DateInput>
  </InputRoot>
  <Description>Please select a time between 9 AM and 5 PM.</Description>
</TimeFieldRoot>

API Reference

PropTypeDefaultDescription
hourCycle
12 | 24
'minute'
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'
-
Determines the smallest unit that is displayed in the time picker.
hideTimeZone
boolean
-
Whether to hide the time zone abbreviation.
shouldForceLeadingZeros
boolean
-
Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
placeholderValue
TimeValue
-
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.
minValue
TimeValue
-
The minimum allowed time that a user may select.
maxValue
TimeValue
-
The maximum allowed time that a user may select.
isDisabled
boolean
-
Whether the input is disabled.
isReadOnly
boolean
-
Whether the input can be selected but not changed by the user.
isRequired
boolean
-
Whether user input is required on the input before form submission.
isInvalid
boolean
-
Whether the input value is invalid.
validate
(value: MappedTimeValue<TimeValue>) => ValidationError | true | null | undefined
-
A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
autoFocus
boolean
-
Whether the element should receive focus on render.
value
TimeValue | null
-
The current value (controlled).
defaultValue
TimeValue | null
-
The default value (uncontrolled).
name
string
-
The name of the input element, used when submitting an HTML form.
validationBehavior
'native' | 'aria'
'aria'
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
children
ReactNode | (values: DateFieldRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode
-
The children of the component. A function may be provided to alter the children based on component state.
className
string
-
The CSS className for the element.
style
CSSProperties | (values: DateFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties
-
The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onChange
(value: MappedTimeValue<TimeValue>) => void
Handler that is called when the value changes.
onFocus
(e: FocusEvent<Target>) => void
Handler that is called when the element receives focus.
onBlur
(e: FocusEvent<Target>) => void
Handler that is called when the element loses focus.
onFocusChange
(isFocused: boolean) => void
Handler that is called when the element's focus status changes.
onKeyDown
(e: KeyboardEvent) => void
Handler that is called when a key is pressed.
onKeyUp
(e: KeyboardEvent) => void
Handler that is called when a key is released.

Accessibility

Keyboard interactions

KeyDescription
Tab
Places focus on the first segment. If a segment is already in focus, moves focus to the next segment. If last segment in in focus, moves focus to the next element in the page tab sequence.
ArrowRight ArrowLeft
Moves focus between segments.
ArrowUp ArrowDown
Increments/decrements the value of the segment.

Last updated on 10/11/2024

Range CalendarDate Field