TimePicker
Native time input wrapper with label, hint, error, and size variants
Category: inputs · WCAG 2.2-AA · time, input, form
Sizes
- sm
- md
- lg
States
- idle
- focused
- error
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Controlled value (HH:mm) |
defaultValue | string | — | The initial value when uncontrolled. |
onValueChange | (value: string) => void | — | Called with the new HH:MM time string when the value changes. |
min | string | — | Minimum allowed value. |
max | string | — | Maximum allowed value. |
step | number | — | Increment between allowed values. |
label | string | — | Text label for the control. |
hint | string | — | Supplementary hint text shown with the control. |
error | string | — | Error message shown when the value is invalid. |
size | 'sm' | 'md' | 'lg' | 'md' | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
disabled | boolean | — | When true, disables the control and removes it from the tab order. |
className | string | — | Additional CSS class names merged onto the root element. |
ariaLabel | string | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. |
Design tokens
--cascivo-color-surface--cascivo-color-bg-subtle--cascivo-color-border--cascivo-color-border-strong--cascivo-color-text--cascivo-color-text-muted--cascivo-color-accent--cascivo-color-destructive--cascivo-radius-input--cascivo-radius-md
When to use
- Capturing a time of day (HH:mm) in a form, such as a meeting or reminder time
- You want the native OS time entry UX with built-in formatting and validation
- A time field that needs a label, hint, error, or min/max bounds
When not to use
- Picking a calendar date — use DatePicker
- A free-form or non-time text value — use Input
How to build an accessible TimePicker in React →
Examples
Basic time picker
<TimePicker label="Meeting time" onValueChange={(v) => console.log(v)} />Related components
- DatePicker — Use when a calendar date is needed instead of a time
- Input — Use for non-time free-text values