# React Native Time Picker

> React Native time picker: iOS wheels, a Material clock dial or columns to click on the web. 12h/24h from the locale, minute intervals, min/max time. Zero native code.

# TimePicker

`TimePicker` is a React Native time picker for hours, minutes and optionally seconds and AM/PM. It looks native on each platform: [wheels on iOS, a Material clock dial on Android, columns to click on the web](#wheels-a-dial-or-a-list), or the one you pick with `display`. The 12h or 24h clock and the AM/PM labels come from the locale automatically.

Picking a length of time, such as a timer or a workout, rather than a time of day? Use [`DurationPicker`](./duration-picker). A start and an end, such as opening hours? Use [`TimeRangePicker`](./time-range-picker).

```tsx
import { TimePicker } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { TimePicker } from 'patine-ui';

export default function Example() {
  const [time, setTime] = useState(new Date());
  return (
    <>
      <TimePicker value={time} onValueChange={setTime} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {time.toLocaleTimeString()}
      </Text>
    </>
  );
}
```

## Example: a pickup time

A takeaway order: the kitchen takes orders from 11:30 to 21:30 in 15-minute slots, and the button reads the time back.

```tsx live
import { useState } from 'react';
import { Button, Text, TimePicker, VStack } from 'patine-ui';

const at = (hours: number, minutes: number) => {
  const date = new Date();
  date.setHours(hours, minutes, 0, 0);
  return date;
};

export default function Example() {
  const [pickup, setPickup] = useState(at(18, 45));
  const time = pickup.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' });
  return (
    <VStack gap="md">
      <VStack gap="xs">
        <Text weight="semibold">Pickup at Lucia’s Trattoria</Text>
        <Text size="sm" color="textSecondary">2 items · $38.50 · ready in about 25 min</Text>
      </VStack>
      <TimePicker value={pickup} onValueChange={setPickup} minTime={at(11, 30)} maxTime={at(21, 30)} minuteInterval={15} />
      <Button>{`Pick up at ${time}`}</Button>
    </VStack>
  );
}
```

## The value is a `Date`

`value` and `onValueChange` use a JavaScript `Date`. Only the hours, minutes and seconds are changed; **the date part is preserved**, so you can pass a full appointment `Date` and get the same day back with a new time. When `showSeconds` is off, seconds and milliseconds are set to `0`.

## 12h / 24h

`format` is `'auto'` by default and is resolved from `locale` (or the device locale). Force it with `'12h'` or `'24h'`.

```tsx live
import { useState } from 'react';
import { View, Text } from 'react-native';
import { TimePicker } from 'patine-ui';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 14, 45));
  return (
    <View style={{ gap: 16 }}>
      <Text style={{ fontWeight: '600' }}>en-US (12h)</Text>
      <TimePicker value={time} onValueChange={setTime} locale="en-US" />
      <Text style={{ fontWeight: '600' }}>de-DE (24h)</Text>
      <TimePicker value={time} onValueChange={setTime} locale="de-DE" />
    </View>
  );
}
```

AM/PM labels come from the locale too (`AM`/`PM`, `a.m.`/`p.m.`, `午前`/`午後`…). Override them with `dayPeriodLabels`, and use `dayPeriodFirst` for languages that put the period before the hour (Chinese, Korean, Japanese):

```tsx live
import { useState } from 'react';
import { TimePicker } from 'patine-ui';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 9, 30));
  return (
    <TimePicker
      value={time}
      onValueChange={setTime}
      format="12h"
      locale="ko-KR"
      dayPeriodFirst
    />
  );
}
```

Hours are zero-padded in 24h mode (`09`) and not in 12h mode (`9`); change that with `padHours`.

## Intervals

`minuteInterval` shows only every n-th minute (5, 10, 15, 30…). `showSeconds` adds a seconds wheel with its own `secondInterval`. A value whose minutes don't fall on the interval is shown rounded **down** (10:07 with a 5-minute step shows 10:05). `TimePickerSheet` and `DateTimePickerSheet` confirm the time as shown, so pressing **Done** without scrolling returns 10:05.

```tsx live
import { useState } from 'react';
import { TimePicker } from 'patine-ui';

export default function Example() {
  const [time, setTime] = useState(new Date(2026, 0, 1, 0, 2, 30));
  return (
    <TimePicker
      value={time}
      onValueChange={setTime}
      format="24h"
      showSeconds
      secondInterval={5}
      minuteInterval={1}
    />
  );
}
```

## Min and max time

`minTime` and `maxTime` limit the selectable **time of day** (their date part is ignored). Hours and minutes outside the range are disabled, and a combination that ends up out of range (for example, changing the hour while sitting on a late minute) is clamped into the range when committed.

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { TimePicker } from 'patine-ui';

const at = (h: number, m = 0) => new Date(2026, 0, 1, h, m);

export default function Example() {
  const [time, setTime] = useState(at(12));
  return (
    <>
      <Text style={{ textAlign: 'center', marginBottom: 8, color: '#6E685E' }}>
        Opening hours: 09:00 – 17:30
      </Text>
      <TimePicker
        value={time}
        onValueChange={setTime}
        minTime={at(9)}
        maxTime={at(17, 30)}
        minuteInterval={15}
        format="24h"
      />
    </>
  );
}
```

## Wheels, a dial or a list

Each [design](../guides/designs) has its own default:

| `display` | Default in | What it is |
| --- | --- | --- |
| `'wheel'` | iOS | Hour, minute and AM/PM wheels |
| `'dial'` | Material | The time in large type above a clock dial. Tap or drag to the hour, lift, then the minutes; tap the hours or minutes above to switch. 24h dials have 1–12 outside and 00, 13–23 on an inner ring. The keyboard button under the dial switches to typing the hours and minutes |
| `'input'` | | Material's time input: the hour and minute fields to type into, without the dial. Compact, so `DateTimePicker` uses it under a Material calendar |
| `'list'` | web | Hours, minutes (and seconds) and AM/PM side by side in a bordered panel, each a column of cells to click, the chosen one kept in the middle |

```tsx
<TimePicker value={time} onValueChange={setTime} display="dial" minuteInterval={5} />
```

A dial or time input has no seconds, so with `showSeconds` they show wheels instead. Screen readers adjust the dial up and down by an hour, or by `minuteInterval`.

## Looping

Hour, minute and second wheels loop by default. Set `loop={false}` for wheels that stop at the ends. The AM/PM wheel never loops.

## Uncontrolled

```tsx
<TimePicker defaultValue={new Date()} onValueChange={(d) => save(d)} />
```

Without `value` or `defaultValue`, the picker starts at the current time.

## In a sheet

```tsx
import { TimePickerSheet } from 'patine-ui';

<TimePickerSheet open={open} onOpenChange={setOpen} title="Alarm" value={time} onConfirm={setTime} minuteInterval={5} />
```

→ [TimePickerSheet](./picker-sheets#timepickersheet)

## In a form field

`TimePickerField` is a field that opens the sheet and shows the confirmed time (`9:30 AM` or `09:30`, from `format` and `locale`). Switch `presentation` in the panel: `auto` opens a dropdown under the field on the web and a bottom sheet on iOS and Android.

→ [Picker fields](./picker-fields)

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date` | — | Selected time (controlled). The date part is preserved. |
| `defaultValue` | `Date` | now | Initial time when uncontrolled. |
| `onValueChange` | `(date: Date) => void` | — | Fires when the user changes the time. Receives a **new** `Date`. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick while scrolling (haptics). |
| `format` | `'12h' \| '24h' \| 'auto'` | `'auto'` | Clock format; `'auto'` reads it from `locale`. |
| `locale` | `string` | device | BCP 47 locale, e.g. `'en-US'`, `'he-IL'`. |
| `display` | `'wheel' \| 'dial' \| 'input' \| 'list'` | from the design | Wheels (iOS), a clock dial (Material), typed fields, or columns to click (web). |
| `minuteInterval` | `number` | `1` | Minute step: 1, 5, 10, 15, 30… |
| `showSeconds` | `boolean` | `false` | Add a seconds wheel. |
| `secondInterval` | `number` | `1` | Second step. |
| `minTime` | `Date` | — | Earliest selectable time of day. |
| `maxTime` | `Date` | — | Latest selectable time of day. |
| `loop` | `boolean` | `true` | Loop the hour / minute / second wheels. |
| `padHours` | `boolean` | `true` for 24h, `false` for 12h | Zero-pad the hour labels. |
| `dayPeriodLabels` | `[string, string]` | from locale | `[am, pm]` labels. |
| `dayPeriodFirst` | `boolean` | `false` | Put the AM/PM wheel before the hours. |
| `separator` | `ReactNode` | `':'` | Shown between the hour, minute and second wheels (not next to AM/PM). |
| `itemHeight` | `number` | `40` | Wheel row height. |
| `visibleItems` | `number` | `5`, or `7` in the list | Visible wheel rows, or cells in each `list` column. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots), for the wheels. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow, over the provider's: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | Test ID. |

## Related

- [Time ranges](./time-range-picker): a start and an end time, such as opening hours
- [Alarm example](/examples/alarm)
- [TimePickerField](./picker-fields): the picker behind a form field
- [DurationPicker](./duration-picker): for a length of time rather than a time of day
