# TimePicker

A time of day in the browser's own time field, styled as a control, with steps, limits and suggestions.

```ehtml Example
import { TimePicker, zonedTime } from "@elements/ui/time-picker";

<TimePicker value={meeting.start} />
<TimePicker value={alarm.at} seconds min="06:00" max="22:00" required />
<TimePicker value={slot.at} step={900} options={["09:00", "09:15", "09:30"]} />
// A day and a time in a zone as one instant; daylight saving gaps move forward.
let at = zonedTime(event.date, event.time, "America/New_York");
```

## Parts

| Part | What it is |
|---|---|
| `TimePicker` | A wrapper with the native `<input type="time">` and a clock icon. |
| `.time-picker-input` | The `<input type="time">`; takes attrs. |
| `.time-picker-icon` | The clock icon at the start. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string` (two-way) | `""` | "HH:MM" or "HH:MM:SS" in 24 hour time, whatever the display. |
| `step` | `number \| "any"` | `0` | Seconds between valid times: 900 for quarter hours. 0 is the browser default (60). "any" accepts every time. |
| `seconds` | `boolean` | `false` | Shows a seconds segment. |
| `min` | `string` | `""` | Earliest valid time. |
| `max` | `string` | `""` | Latest valid time. |
| `refuseOutOfRange` | `boolean` | `false` | A typed time outside min and max is shown invalid and never reaches the value. |
| `options` | `string[]` | `[]` | Suggested times, offered by the browser as a list. |
| `name` | `string` | `""` | Form field name. |
| `form` | `string` | `""` | The id of a form elsewhere on the page. |
| `required` | `boolean` | `false` | The form will not submit while empty. |
| `disabled` | `boolean` | `false` | Not interactive; not submitted. |
| `readOnly` | `boolean` | `false` | Shown, not editable. |
| `invalid` | `boolean` | `false` | aria-invalid and the danger border. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height and text from the control tokens. |
| `block` | `boolean` | `false` | Full width. |
| `icon` | `boolean` | `true` | A clock icon at the start. |
| `indicator` | `boolean` | `false` | Shows the browser's own picker button. It also shows whenever options are set, since in Chromium that button is what opens the suggestions. |
| `label` | `string` | `""` | aria-label when there is no visible label. |
| `class` | `string` | `""` | Classes on the wrapper. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the input: id, aria-\*, data-\*. |
| `onValueChange` | `(value: string) => void` | `() => {}` | Every edit. |
| `onchange` | `(e: Event) => void` | `() => {}` | The native change event. |

## Keyboard

| Keys | Action |
|---|---|
| `ArrowUp / ArrowDown` | Steps the focused segment (native). |
| `ArrowLeft / ArrowRight` | Moves between segments (native). |
| `Digits` | Type the focused segment; it moves on when full. |
| `Backspace` | Clears the focused segment. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-size` | `"sm" \| "md" \| "lg"` | root |
| `data-disabled` | present while disabled | root |

## Accessibility

- A native time input: screen readers announce it as a time field with its segments.
- The hour cycle (12 or 24 hours) follows the user's locale.
- Named by its Field label or the label attribute; aria-invalid with invalid.

## See also

- [Calendar](calendar): A month grid for picking one date, several dates or a range, with keyboard navigation across months.
- [DatePicker](date-picker): A button or text field that picks one date from a Calendar in a popover.
- [DateRangePicker](date-range-picker): A button that picks a start and end date from a two-month range Calendar in a popover.