# Time picker

> Type “9:30 pm” or fling the hour, minute and AM/PM drums; both paths settle into one plain HH:mm value.

A time field should be quick when you know the time and tactile when you need to find it. This one accepts forgiving typed input such as “9”, “930” or “9:30 pm”, then opens into real kinetic hour, minute and period drums. Every path normalises to a plain HH:mm string, observes minute steps and optional opening hours, and keeps the field, wheels and form value in sync.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/time-picker.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`, `wheel-picker`
- Docs and live preview: https://hairlineui.com/ui/time-picker
- Registry item (source): https://hairlineui.com/r/time-picker.json

## Usage

```tsx
import { TimePicker } from "@/components/time-picker";

<TimePicker
  label="Appointment"
  value={time}
  onValueChange={setTime}
  hour12
  minuteStep={15}
  min="09:00"
  max="17:30"
/>
```

## A booking time with opening hours

Keep the value as a string beside your existing YYYY-MM-DD date. The component handles display and input; your booking endpoint remains the source of availability.

```tsx
"use client";

import * as React from "react";
import { TimePicker } from "@/components/time-picker";

export function BookingTime() {
  const [time, setTime] = React.useState<string | null>("10:30");

  async function save() {
    await fetch("/api/booking", {
      method: "POST",
      body: JSON.stringify({ date: "2026-11-04", time }),
    });
  }

  return (
    <TimePicker
      label="Start time"
      name="startTime"
      value={time}
      onValueChange={setTime}
      minuteStep={15}
      min="09:00"
      max="17:30"
      hint="Appointments run from 09:00 to 17:30."
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | `string \| null` | – | A 24-hour HH:mm string; null means no time. |
| `onValueChange` | `(value: string \| null) => void` | – | Called when a wheel, typed value or shortcut changes the time. |
| `hour12` | `boolean` | `false` | Uses 12-hour display and adds an AM/PM drum. |
| `minuteStep` | `number` | `5` | Minute drum interval and typed-value snapping. |
| `min / max` | `string` | – | Optional inclusive HH:mm limits. |
| `name` | `string` | – | Submits HH:mm through a hidden input. |
| `placeholder` | `string` | `"Choose a time"` | Trigger text when the value is null. |
| `label / hint / error` | `ReactNode` | – | Shared field label, help and external error. |
| `disabled / id / className` | `boolean / string / string` | – | Standard field state and layout customisation. |

## States

- **rest**: The field shows a formatted time or placeholder beside a quiet clock icon.
- **open**: The typed field and kinetic drums rise from the trigger; the text is selected for a quick replacement.
- **wheel**: Each drum flings and settles onto a row; the hours and minutes on the field roll the way the time moved, and AM/PM morphs.
- **typed error**: Invalid or out-of-hours input stays put, shakes once and explains the accepted range.
- **done**: Enter or Done applies the value, closes the panel and returns keyboard focus to the field.

## What it handles

Time input combines parsing, 12-hour conversion, stepping, limits and touch gestures. This uses the library’s proven drum physics rather than a native time control or another gesture implementation.

- **Forgiving typed input**: Reads 9, 930, 09:30, 9:30 pm and 21:30, then settles them into a consistent value.
- **Real kinetic drums**: Hours, minutes and AM/PM use pointer flings, inertia, rubber-banded ends and keyboard steps from WheelPicker.
- **One plain value**: Controlled and uncontrolled fields both use HH:mm or null, with no Date object or time-zone shift.
- **Minute steps and limits**: Typed and picked values snap to the minute step and stay inside optional min and max opening hours.
- **Now, Clear and Done**: Common shortcuts stay in the panel; Done applies typed input and returns focus to the trigger.
- **Forms and accessibility**: A hidden input submits HH:mm, each drum is a labelled spinbutton, and the dialog has Escape and outside dismissal.

## Replaces

native <input type="time">, custom hour and minute selects, 12/24-hour conversion helpers, time parsing and normalisation, kinetic wheel wiring

## Where it fits

- **Reminders and tasks**: Set a due time without adopting a full calendar.
- **Booking forms**: Pick arrival and appointment times in fixed minute steps.
- **Opening hours**: Limit selections to the hours a shop or team operates.
- **Scheduled publishing**: Choose a posting time alongside an existing date field.

## Notes

- parseTime(input) is exported for integrations that need the same typed-time parsing.
- Wheels are spinbuttons: arrows step, Page Up/Down jump five rows and Home/End move to the ends.
- Values are deliberately plain strings, not Date objects; combine them with a date and time zone in your own scheduling logic.
- Reduced motion is handled by the shared WheelPicker and floating-panel transitions.

License: MIT (https://hairlineui.com/license#components)
