# React Native Duration Picker

> React Native duration and countdown timer picker: iOS wheels, Material number boxes or columns to click on the web, with unit labels, the value in seconds, min/max and minute intervals. In a bottom sheet or a form field. Zero native code, works in Expo Go.

# DurationPicker

`DurationPicker` picks a **length of time**, such as a timer, a workout, a cooking time or a reminder: hours, minutes and optionally seconds, each with its unit beside it. It looks native on each platform: [wheels like the iOS countdown timer, number boxes to type into in Material, columns to click on the web](#wheels-boxes-or-columns), or the one you pick with `display`. The value is a number of seconds.

For a **time of day** (an alarm at 7:30 AM), use [`TimePicker`](./time-picker). A duration has no AM/PM and no locale clock, its hours don't wrap at midnight, and its limits are lengths, not times.

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

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

export default function Example() {
  const [seconds, setSeconds] = useState(25 * 60);
  return (
    <>
      <DurationPicker value={seconds} onValueChange={setSeconds} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {seconds} s = {formatDuration(seconds)}
      </Text>
    </>
  );
}
```

## Example: a kitchen timer

A recipe's timer: set the minutes and seconds, then Start counts down from them. While it runs, the picker gives way to the time left.

```tsx live
import { useEffect, useState } from 'react';
import { Box, Button, DurationPicker, HStack, Progress, Text, VStack, formatDuration } from 'patine-ui';

export default function Example() {
  const [length, setLength] = useState(12 * 60);
  const [left, setLeft] = useState<number | null>(null);
  useEffect(() => {
    if (left === null || left === 0) return;
    const id = setTimeout(() => setLeft(left - 1), 1000);
    return () => clearTimeout(id);
  }, [left]);
  const running = left !== null;
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 360 }}>
      <Text weight="semibold">Soft-boiled eggs, then the risotto</Text>
      {running ? (
        <VStack gap="sm" align="center">
          <Text size="3xl" weight="semibold">
            {String(Math.floor(left / 60)).padStart(2, '0')}:{String(left % 60).padStart(2, '0')}
          </Text>
          <Progress value={((length - left) / length) * 100} accessibilityLabel="Time passed" />
          <Text color={left === 0 ? 'success' : 'textSecondary'}>{left === 0 ? 'Time’s up!' : `of ${formatDuration(length)}`}</Text>
        </VStack>
      ) : (
        <DurationPicker value={length} onValueChange={setLength} showHours={false} showSeconds secondInterval={5} max={90 * 60} />
      )}
      <HStack gap="sm">
        <Button style={{ flex: 1 }} disabled={!length} onPress={() => setLeft(running ? null : length)}>
          {running ? 'Reset' : 'Start'}
        </Button>
      </HStack>
    </Box>
  );
}
```

## The value is in seconds

`value`, `defaultValue` and `onValueChange` use a number of seconds: `5400` is 1 h 30 min. Store it as is, or turn it into text with [`formatDuration`](#formatduration). Without `value` or `defaultValue`, the picker starts at `0`.

## Wheels, boxes or columns

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

| `display` | Default in | What it is |
| --- | --- | --- |
| `'wheel'` | iOS | Hours, minutes and seconds wheels with their units at the selection band, like the iOS countdown timer |
| `'input'` | Material | A box per unit to type the number into, as in Material's time input. A number that isn't one of the steps yet (`3` on the way to `30` with `minuteInterval={15}`) waits for the next digit |
| `'list'` | web | A column of cells per unit under its label, the chosen one filled, as in `TimePicker` on the web |

```tsx
<DurationPicker value={seconds} onValueChange={setSeconds} display="wheel" />
```

## Hours, minutes and seconds

Hours and minutes show by default. `showSeconds` adds a seconds wheel, and `showHours={false}` drops the hours, so the minutes can count past 59 up to `max` (`max={90 * 60}` for a 90-minute run):

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

export default function Example() {
  const [rest, setRest] = useState(90);
  return <DurationPicker value={rest} onValueChange={setRest} showHours={false} showSeconds secondInterval={5} />;
}
```

## Min, max and intervals

`min` and `max` are in seconds. Values outside them are dimmed, and a combination that lands outside (such as 2 h with 45 min while the max is 2 h) is pulled back to the nearest limit. Without `max`, the hours go up to 23, or the minutes up to 59 without hours.

`minuteInterval` and `secondInterval` show every n-th minute or second. A value between steps shows rounded **down**, and `DurationPickerSheet` confirms what the wheels show.

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

export default function Example() {
  const [workout, setWorkout] = useState(45 * 60);
  return <DurationPicker value={workout} onValueChange={setWorkout} min={10 * 60} max={3 * 3600} minuteInterval={5} />;
}
```

## Unit labels and other languages

`labels` sets the unit beside each wheel, box or column and in the field text. Screen readers read each one as "Hours", "Minutes" or "Seconds", followed by its value.

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

const GERMAN = { hours: 'Std.', minutes: 'Min.', seconds: 'Sek.' };

export default function Example() {
  const [seconds, setSeconds] = useState(3600);
  return <DurationPicker value={seconds} onValueChange={setSeconds} labels={GERMAN} />;
}
```

## `formatDuration`

Turns seconds into the field's text: the units that aren't zero, exact to the second.

```ts
formatDuration(5400); // '1 h 30 min'
formatDuration(95); // '1 min 35 s'
formatDuration(5400, { showHours: false }); // '90 min'
formatDuration(0); // '0 min'
```

It takes `showHours` and `labels`, like the picker.

## In a sheet

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

<DurationPickerSheet open={open} onOpenChange={setOpen} title="Timer" value={seconds} onConfirm={setSeconds} />
```

It takes the [shared sheet props](./picker-sheets#shared-props) and the picker's, and keeps a draft until **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

## In a form field

`DurationPickerField` opens the sheet and shows the confirmed duration, like `1 h 30 min`. 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` | `number` | — | Selected duration in seconds (controlled). |
| `defaultValue` | `number` | `0` | Initial duration when uncontrolled. |
| `onValueChange` | `(seconds: number) => void` | — | Fires when the user changes the duration. |
| `onValueChanging` | `(seconds: number) => void` | — | Fires on every tick while scrolling (haptics). |
| `display` | `'wheel' \| 'input' \| 'list'` | from the design | Wheels (iOS), boxes to type into (Material), or columns to click (web). |
| `showHours` | `boolean` | `true` | Show the hours wheel. Without it, minutes count past 59, up to `max`. |
| `showSeconds` | `boolean` | `false` | Add a seconds wheel. |
| `min` | `number` | `0` | Shortest selectable duration, in seconds. |
| `max` | `number` | 23 h 59 min 59 s, or 59 min 59 s without hours | Longest selectable duration, in seconds. |
| `minuteInterval` | `number` | `1` | Minute step: 1, 5, 15… |
| `secondInterval` | `number` | `1` | Second step. |
| `labels` | `{ hours?, minutes?, seconds? }` | `{ hours: 'h', minutes: 'min', seconds: 's' }` | Units beside the wheels and in the field. |
| `loop` | `boolean` | `true` | Loop the minute and second wheels. Hours never loop. |
| `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. The `separator` slot styles their unit labels. |
| `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. Each wheel, box or column gets `${testID}-hours`, `-minutes` and `-seconds`. |

`DurationPickerSheet` takes these plus the [sheet props](./picker-sheets#shared-props) and `onConfirm(seconds)`. `DurationPickerField` takes the sheet's props plus the [field props](./picker-fields#props).

## Related

- [TimePicker](./time-picker): for a time of day
- [Workout timer example](/examples/workout-timer)
- [MultiWheelPicker](./multi-wheel-picker): build other unit pickers with the column `suffix`
