# TimePicker

> Enter a time of day with keyboard-friendly hour and minute segments.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/time-picker

TimePicker uses separate spinbutton segments, the same model as the native time input: type digits (focus advances automatically) or use the arrow keys. The value is always 24-hour HH:MM (or HH:MM:SS) regardless of display, so it is easy to store and submit. The hour cycle follows the locale unless set.

## Import

```tsx
import { TimePicker } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { FormField, TimePicker } from '@bindshq/stance-react';

export function Basic() {
  return (
    <FormField label="Send daily digest at" description="Europe/London" style={{ width: 220 }}>
      <TimePicker hourCycle={24} defaultValue="09:00" name="digestTime" />
    </FormField>
  );
}
```

### 12-hour with AM/PM

```tsx
import { useState } from 'react';
import { FormField, TimePicker } from '@bindshq/stance-react';

export function TwelveHour() {
  const [time, setTime] = useState<string | null>('16:30');
  return (
    <div style={{ display: 'grid', gap: 8, width: 220 }}>
      <FormField label="Meeting starts">
        <TimePicker hourCycle={12} value={time} onValueChange={setTime} />
      </FormField>
      <p style={{ margin: 0, fontSize: 13 }}>Stored value: {time ?? 'None'}</p>
    </div>
  );
}
```

### Quarter-hour steps

Arrow keys move minutes in 15-minute increments.

```tsx
import { FormField, TimePicker } from '@bindshq/stance-react';

export function Step() {
  return (
    <FormField label="Deployment slot" style={{ width: 220 }}>
      <TimePicker hourCycle={24} step={15} defaultValue="14:00" />
    </FormField>
  );
}
```

### Seconds, clearable and disabled

```tsx
import { TimePicker } from '@bindshq/stance-react';

export function WithSeconds() {
  return (
    <div style={{ display: 'grid', gap: 12, width: 240 }}>
      <TimePicker
        aria-label="Sync time"
        hourCycle={24}
        showSeconds
        clearable
        defaultValue="06:00:30"
      />
      <TimePicker aria-label="Locked" hourCycle={24} disabled defaultValue="12:00" />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| TimePicker | `value / defaultValue` | `string \| null` | None | 24-hour `HH:MM` or `HH:MM:SS`; null while incomplete. |
| TimePicker | `onValueChange` | `(value: string \| null) => void` | None | Called when the time changes. |
| TimePicker | `hourCycle` | `12 \| 24` | `locale` | Display cycle. |
| TimePicker | `locale` | `string` | None | Used to pick the default hour cycle. |
| TimePicker | `step` | `number` | `1` | Minute increment for arrow keys. |
| TimePicker | `showSeconds` | `boolean` | `false` | Adds a seconds segment. |
| TimePicker | `name` | `string` | None | Hidden input name for form submission. |
| TimePicker | `clearable` | `boolean` | `false` | Show a clear button. |
| TimePicker | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field height. |
| TimePicker | `disabled / required / invalid` | `boolean` | None | States, also inherited from FormField. |
| TimePicker | `labels` | `Partial<TimePickerLabels>` | None | Segment names and AM/PM text. |

## Accessibility

- A group named by its FormField label, containing spinbuttons named Hours, Minutes (Seconds) and AM/PM.
- Each spinbutton exposes aria-valuenow, min, max and a text value; empty segments announce “Empty”.
- Each segment is a tab stop, matching native time inputs.

## Keyboard

| Keys | Action |
| --- | --- |
| `↑` `↓` | Increment / decrement the segment (wraps). |
| `0 to 9` | Type a value; focus advances when the segment is complete. |
| `←` `→` | Move between segments. |
| `Home` `End` | Minimum / maximum value. |
| `Backspace` | Clear the segment. |
| `A` `P` | Set AM / PM. |

## Guidelines

**Do**

- State the time zone in the description.
- Use step for scheduling in fixed slots.

**Don’t**

- Use for durations; use NumberInput.

## Related

- https://stanceui.com/components/date-picker
- https://stanceui.com/components/number-input