Date & Time

Time Picker

Popover hour/minute (and optional second) selection, 12h or 24h.

Import

tsx

import { TimePicker } from "@cooud-ui/ui";

bash

npx cooud-ui add time-picker

Examples

12-hour clock

A controlled picker with a `Clock` trigger and scrollable hour / minute / AM–PM wheels. Pass `value` and `onChange`; the callback always emits a normalized `{ hours, minutes, seconds }` (24-hour `hours`).

Selected 09:30

tsx

// Fixed initial value keeps SSR + client identical (avoids hydration drift).
const [time, setTime] = useState<TimeValue | undefined>(() => ({ hours: 9, minutes: 30 }));

return (
  <div className="flex flex-col gap-3">
    <TimePicker value={time} onChange={setTime} aria-label="Meeting time" />
    <span className="text-sm text-fg-tertiary">
      {time
        ? `Selected ${String(time.hours).padStart(2, "0")}:${String(time.minutes).padStart(2, "0")}`
        : "No time selected yet."}
    </span>
  </div>
);

24-hour with seconds

Set `hourCycle={24}` for a 0–23 column (no AM/PM), tune column granularity with `minuteStep`, and reveal a seconds wheel with `showSeconds`.

tsx

const [time, setTime] = useState<TimeValue | undefined>(() => ({
  hours: 14,
  minutes: 45,
  seconds: 0,
}));

return (
  <TimePicker
    value={time}
    onChange={setTime}
    hourCycle={24}
    minuteStep={5}
    showSeconds
    aria-label="Broadcast start"
  />
);

Disabled

Set `disabled` to lock the trigger and the whole panel while still displaying its current value — useful for read-only or gated slots.

tsx

<TimePicker defaultValue="08:00" disabled aria-label="Locked slot" />

API Reference

Generated from the component's exported types.

TimePickerProps

Prop	Type	Default	Description
`value`	`TimeValue \| string`	—	Controlled value — a `{ hours, minutes, seconds }` object (24h `hours`) or a `"HH:mm"` / `"HH:mm:ss"` string.
`defaultValue`	`TimeValue \| string`	—	Initial value for uncontrolled usage.
`onChange`	`(value: TimeValue) => void`	—	Fired with the normalized `{ hours, minutes, seconds }` whenever the time changes.
`hourCycle`	`12 \| 24`	`12`	`12` renders a 1–12 hour column plus an AM/PM column; `24` renders a 0–23 column.
`minuteStep`	`number`	`1`	Granularity of the minute column, in minutes.
`showSeconds`	`boolean`	`false`	Render a seconds column.
`secondStep`	`number`	`1`	Granularity of the seconds column, in seconds.
`placeholder`	`string`	`"Select time"`	Text shown on the trigger when no value is set.
`disabled`	`boolean`	`false`	Disable the trigger and the whole panel.
`aria-label`	`string`	—	Accessible name for the trigger when there is no visible label.
`className`	`string`	—	Extra classes for the trigger button.
`contentClassName`	`string`	—	Extra classes for the popover panel.
`id`	`string`	—	Native id for the trigger.
`align`	`"start" \| "center" \| "end"`	`"start"`	Popover alignment relative to the trigger.