TimePicker

A composable time picker that pairs a segmented time input with a popover containing wheel-based spinbutton columns. Values are HH:mm or HH:mm:ss strings, with null as the empty state.

Anatomy

TimePicker.Root owns the value and open state. TimePicker.Input renders locale-resolved segments, TimePicker.Trigger opens the popover, and TimePicker.Clock resolves the visible wheel columns from root state (granularity, hourCycle) in stable order: hour → minute? → second? → dayPeriod?. The column snippet customizes each wheel; omit it for default rendering.

<script>
	import { TimePicker } from '@human-kit/ui/timepicker';
</script>

<TimePicker.Root>
	<TimePicker.Input aria-label="Time input">
		{#snippet children(segment)}
			<TimePicker.Segment {segment} />
		{/snippet}
	</TimePicker.Input>
	<TimePicker.Trigger />

	<TimePicker.Popover>
		<TimePicker.Clock />
	</TimePicker.Popover>
</TimePicker.Root>

Min and max bounds

minValue and maxValue constrain both the typed input and the wheels. Out-of-range wheel items are rendered with data-disabled; typed out-of-range values mark the input invalid instead of being auto-corrected. Midnight-wrapping ranges are not supported.

12-hour cycle

Set hourCycle={12} to render an AM/PM segment and a day-period wheel column. Values are always normalized to 24-hour strings internally — the 12-hour rendering only affects the UI.

Usage guidelines

• Use value with onChange for controlled state and defaultValue for uncontrolled state; the empty state is null.
• granularity controls the editable units: 'hour', 'minute' (default), or 'second'. granularity="hour" emits HH:00 values.
• Use hourStep, minuteStep, and secondStep to restrict selectable values to increments.
• Use open / defaultOpen / onOpenChange to control the popover; wheel selection commits immediately on snap.
• TimePicker.Popover forwards Popover.Content props such as placement (default bottom), offset, and shouldFlip.
• Wrap in a LocaleProvider to localize segment order, day-period labels, and the default hour cycle.

Accessibility

• Segment accessible names are resolved automatically from the active locale.
• TimePicker.Input exposes aria-invalid and data-invalid when the current segment draft is not committable.
• Each wheel column exposes role="spinbutton" with aria-valuenow, aria-valuetext, aria-valuemin, and aria-valuemax.
• Inside the popover, ArrowUp/ArrowDown step the focused column, ArrowLeft/ArrowRight move between columns, and Home/End jump to the column edges.
• Popover focus defaults to the first wheel column; Escape and outside presses close it.

API reference

Root

The stateful container. Owns the committed time value, the popover open state, and the granularity/hour-cycle configuration shared by the input and clock.

* required. Native HTML attributes of the underlying element are also accepted.

Input

The segmented time input. Iterates the locale-resolved segments and passes each to the children snippet.

* required. Native HTML attributes of the underlying element are also accepted.

Segment

One editable or literal segment of the time (hour, minute, second, day period, or separator). Supports typing and arrow-key stepping.

* required. Native HTML attributes of the underlying element are also accepted.

Trigger

Button that opens and closes the clock popover.

* required. Native HTML attributes of the underlying element are also accepted.

Popover

The floating panel that hosts the clock. Forwards Popover.Content props (placement, offset, shouldFlip, …); open state, trigger wiring, and id are controlled internally. Placement defaults to bottom and initial focus lands on the first wheel column.

* required. Native HTML attributes of the underlying element are also accepted.

Clock

The wheel surface inside the popover. Resolves visible columns from root state (granularity, hourCycle) in stable order: hour → minute? → second? → dayPeriod?.

* required. Native HTML attributes of the underlying element are also accepted.

WheelColumn

One scrollable wheel (role="spinbutton") for one editable segment: hour, minute, second, or dayPeriod.

* required. Native HTML attributes of the underlying element are also accepted.

WheelItem

Headless item inside a wheel column. Renders one option and exposes its state through data attributes, leaving all visual styling to consumers.

* required. Native HTML attributes of the underlying element are also accepted.