Time picker
Choose a time using the original radial clock face.
Installation
pnpm dlx shadcn@latest add \
https://react-toolbox.io/r/time-picker.json \
https://react-toolbox.io/r/dropdown.json \
https://react-toolbox.io/r/button.jsonNew here? Set up your project first. Styles, fonts, and required components are included. The command includes the components used by the examples below.
Usage
Values are Date objects. Use format="24hr" for a 24-hour clock or format="ampm" for a 12-hour clock.
Composition
Compose a local time window with minute steps and bounds. Keep the date and IANA time zone explicit in your application’s scheduling data.
Show composition code
'use client';
import { useState } from 'react';
import { TimePicker } from '@/components/ui/material/time-picker';
import { Dropdown } from '@/components/ui/material/dropdown';
import { Button } from '@/components/ui/material/button';
export default function SchedulingComposition() {
const [start, setStart] = useState<Date | null>(null);
const [end, setEnd] = useState<Date | null>(null);
const [zone, setZone] = useState('Europe/Madrid');
const [saved, setSaved] = useState('');
return (
<form
className="max-w-sm"
onSubmit={(event) => {
event.preventDefault();
if (start && end)
setSaved(
`${start.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}–${end.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })} in ${zone}`,
);
}}
>
<TimePicker
label="Starts at"
value={start}
onChange={setStart}
minuteStep={15}
clearable
onClear={() => setStart(null)}
required
/>
<TimePicker
label="Ends at"
value={end}
onChange={setEnd}
minTime={start ?? undefined}
minuteStep={15}
clearable
onClear={() => setEnd(null)}
required
/>
<Dropdown
label="Time zone"
source={['Europe/Madrid', 'Europe/London', 'America/New_York']}
value={zone}
onChange={(value) => setZone(String(value))}
/>
<p className="mb-4 text-toolbox-caption text-toolbox-text-secondary">
Times are wall-clock values in the selected zone. Resolve them to instants with the booking date when saving.
</p>
<Button type="submit" primary raised>
Save time window
</Button>
<p role="status" className="mt-4 text-toolbox-body">
{saved}
</p>
</form>
);
}
State and callbacks
- Use
value/onChange, ordefaultValuefor internal state and form reset. The dialog edits a draft time until confirmation. - Visibility is internal by default. Use
defaultOpento initialize it oropen/onOpenChangeto control it. When controlled, updateopenfromonOpenChange;onDismissreports dismissal.
API reference
Key props and defaults. Full types and inline documentation are included with the source in material/time-picker.
TimePicker
| Property | Type | Default |
|---|---|---|
clearable | booleanShow a clear action. Controlled consumers clear by setting value to null. | — |
defaultOpen | boolean | — |
defaultValue | Date | — |
format | TimeFormat | '24hr' |
labels | Partial<TimePickerLabels> | — |
layout | 'portrait' | 'landscape' | 'responsive'Preserve portrait, force landscape, or adapt to wide landscape viewports. | — |
maxTime | Date | — |
minTime | DateInclusive local clock bounds. A minimum later than the maximum permits an overnight interval. | — |
minuteStep | numberAllowed minute marks within each hour, from 1 through 60. Defaults to 1. | — |
onChange | (time: Date, event?: React.MouseEvent<HTMLElement>) => void | — |
onOpenChange | (open: boolean) => void | — |
open | boolean | — |
readOnly | booleanKeep the value focusable and submitted while preventing edits and validation. | — |
value | Date | null | — |
Material guidelines
- Use the clock face for selecting a specific time, with separate hour and minute steps and an explicit confirmation.
- Choose the 12-hour or 24-hour format to suit the user’s preferences. The application supplies that preference; the component does not infer it automatically.