Clock

A standalone wheel-based time picker with spinbutton columns for hour, minute, second, and day-period selection. It can be used independently or composed inside TimePicker via TimePicker.Clock.

Anatomy

Clock.Root resolves the visible columns from granularity and hourCycle in stable order (hour → minute? → second? → dayPeriod?). The column snippet customizes each wheel; Clock.Axis draws a root-level overlay (such as a central selection band) across all columns. When no column snippet is provided, default columns are rendered automatically.

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

<Clock.Root value="14:30" granularity="minute" hourCycle={24} class="flex gap-2">
	{#snippet column(col)}
		<Clock.WheelColumn type={col.type} class="h-44 w-16">
			{#snippet children(option)}
				<Clock.WheelItem type={col.type} {option} />
			{/snippet}
		</Clock.WheelColumn>
	{/snippet}
	<Clock.Axis />
</Clock.Root>

Min and max bounds

minValue and maxValue constrain the selectable time. Out-of-range items are rendered with data-disabled so they stay visible but cannot be committed. Midnight-wrapping ranges are not supported.

12-hour cycle

Set hourCycle={12} to render a day-period column. Values are always normalized to 24-hour HH:mm strings internally — the 12-hour rendering only affects the UI segments.

Usage guidelines

• Use value with onChange for controlled state and defaultValue for uncontrolled state; values are HH:mm or HH:mm:ss strings.
• granularity controls which columns render: 'hour', 'minute' (default), or 'second'. granularity="hour" emits HH:00 values.
• hourCycle defaults to the active locale; set 12 or 24 to force a cycle.
• Use hourStep, minuteStep, and secondStep to restrict selectable values to increments.
• Wrap in a LocaleProvider to localize day-period labels and the default hour cycle.
• Wheel selection commits immediately on snap.

Accessibility

• Each wheel column exposes role="spinbutton" with aria-valuenow, aria-valuetext, aria-valuemin, and aria-valuemax.
• ArrowUp/ArrowDown change the focused column's value by one step.
• ArrowLeft/ArrowRight move focus between columns.
• Home/End jump to the first/last value in the column.

API reference

Root

The stateful container. Resolves visible wheel columns from granularity and hourCycle in stable order (hour → minute? → second? → dayPeriod?) and renders default columns when no column snippet is provided.

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

Axis

Root-level visual overlay rendered across all columns, e.g. a central selection band aligned with the snapped items.

* 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.