Skip to main content

Time picker

Help people enter or select a time from a list with a time picker and keyboard controls.

Examples

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
hh:mm
time-picker-demo.tsx
import { TimePicker } from '@uswds-tailwind/react'
export default function TimePickerDemo() {
return (
<div className="max-w-xs">
<TimePicker.Root>
<TimePicker.Label>Appointment time</TimePicker.Label>
<div id="appointment-time-hint" className="text-gray-50">hh:mm</div>
<TimePicker.Control>
<TimePicker.Input aria-describedby="appointment-time-hint" />
<TimePicker.IndicatorGroup>
<TimePicker.ClearButton />
<TimePicker.ToggleButton />
</TimePicker.IndicatorGroup>
</TimePicker.Control>
<TimePicker.List>
{({ options }) => options.map(option => (
<TimePicker.Item key={option.id} {...option}>
{option.label}
</TimePicker.Item>
))}
</TimePicker.List>
</TimePicker.Root>
</div>
)
}

Component API

TimePicker uses the Combobox parts. Root supplies half-hour options and time-aware filtering by default; pass options to replace the generated list.

Root<div>

Manages time selection, query text, filtering, and list visibility.

PropTypeDefaultDescription
options{ value: string; label: string }[]—Replaces the generated half-hour time options.
defaultValuestring—Initial selected time.
onValueChange({ value, label }) => void—Receives the selected time value and its visible label.
disableFilteringboolean—Shows supplied options without filtering.
disabledbooleanfalseDisables selection.
requiredboolean—Requires a value.
showClearButtonbooleantrueRenders the clear button when true.
showToggleButtonbooleantrueRenders the toggle button when true.
AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.
data-disabledPresent when disabledStyle the disabled state.

Label<label>

Names the time field.

Control<div>

Groups the input and buttons.

Input<input>

Receives a typed time query.

List<ul>

Displays matching time options.

PropTypeDescription
childrenReactNode | ({ options }) => ReactNodeRenders items from the filtered options or supplied children.
AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

Item<li>

Spread a rendered option onto Item, including its generated id, value, and label.

PropTypeDescription
idstring (required)Generated ID from the rendered option.
valuestring (required)Option value.
labelstring (required)Option label.
AttributeValuePurpose
aria-selectedtrue | falseStyles the selected option.
data-highlightedPresent when highlightedStyles the highlighted option.

EmptyItem<li>

Displays when no option matches.

IndicatorGroup<div>

Groups clear and toggle buttons.

ClearButton<button>

Clears the selected time.

ToggleButton<button>

Opens or closes the option list.

Accessibility

Provide a visible Label or another accessible name. Keep Item indices aligned with the filtered options passed to List.