---
title: Time picker (React) - USWDS + Tailwind
description: Help people enter or select a time from a list with a time picker
  and keyboard controls.
---

# Time picker

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

## Examples

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

| Prop | Type | Default | Description |
| - | - | - | - |
| `options` | `{ value: string; label: string }[]` | `—` | Replaces the generated half-hour time options. |
| `defaultValue` | `string` | `—` | Initial selected time. |
| `onValueChange` | `({ value, label }) => void` | `—` | Receives the selected time value and its visible label. |
| `disableFiltering` | `boolean` | `—` | Shows supplied options without filtering. |
| `disabled` | `boolean` | `false` | Disables selection. |
| `required` | `boolean` | `—` | Requires a value. |
| `showClearButton` | `boolean` | `true` | Renders the clear button when true. |
| `showToggleButton` | `boolean` | `true` | Renders the toggle button when true. |

| Attribute | Value | Purpose |
| - | - | - |
| `data-state` | `open \| closed` | Style the open and closed states. |
| `data-disabled` | `Present when disabled` | Style 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.

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode \| ({ options }) => ReactNode` | Renders items from the filtered options or supplied children. |

| Attribute | Value | Purpose |
| - | - | - |
| `data-state` | `open \| closed` | Style the open and closed states. |

### Item `<li>`

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

| Prop | Type | Description |
| - | - | - |
| `id` | `string (required)` | Generated ID from the rendered option. |
| `value` | `string (required)` | Option value. |
| `label` | `string (required)` | Option label. |

| Attribute | Value | Purpose |
| - | - | - |
| `aria-selected` | `true \| false` | Styles the selected option. |
| `data-highlighted` | `Present when highlighted` | Styles 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.