# React Native Multi-Column Wheel Picker

> Several React Native wheel pickers side by side sharing one selection band — for units, measurements, compound values and custom date/time layouts.

# MultiWheelPicker

`MultiWheelPicker` puts several React Native [`WheelPicker`](./wheel-picker)s side by side, sharing **one** selection band, the way iOS shows time and date wheels. The wheels of `TimePicker`, `DurationPicker` and `DateWheelPicker` are built on it. Use it for durations, heights, weights, currency + amount, or anything multi-column.

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

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

const range = (n: number) =>
  Array.from({ length: n }, (_, i) => ({
    label: String(i).padStart(2, '0'),
    value: i,
  }));

export default function Example() {
  const [h, setH] = useState(1);
  const [m, setM] = useState(30);
  const [s, setS] = useState(0);
  return (
    <MultiWheelPicker
      separator=":"
      columns={[
        { key: 'h', items: range(24), value: h, onValueChange: setH },
        { key: 'm', items: range(60), value: m, onValueChange: setM, loop: true },
        { key: 's', items: range(60), value: s, onValueChange: setS, loop: true },
      ]}
    />
  );
}
```

## Example: how often to repeat

A reminder's Repeat setting: a number and a unit side by side. The unit names follow the number (1 week, 3 weeks), and the line under the wheels says when the next one is.

```tsx live
import { useState } from 'react';
import { Box, MultiWheelPicker, Text } from 'patine-ui';

const UNITS = [
  { value: 'day', days: 1 },
  { value: 'week', days: 7 },
  { value: 'month', days: 30 },
];

export default function Example() {
  const [every, setEvery] = useState(2);
  const [unit, setUnit] = useState('week');
  const plural = (u: string) => (every === 1 ? u : `${u}s`);
  const next = new Date();
  next.setDate(next.getDate() + every * UNITS.find((u) => u.value === unit)!.days);
  return (
    <Box border radius="lg" padding="md" gap="sm" style={{ width: '100%', maxWidth: 360 }}>
      <Text weight="semibold">Water the plants</Text>
      <MultiWheelPicker
        columns={[
          { key: 'every', items: Array.from({ length: 30 }, (_, i) => ({ label: String(i + 1), value: i + 1 })), value: every, onValueChange: setEvery },
          { key: 'unit', items: UNITS.map((u) => ({ label: plural(u.value), value: u.value })), value: unit, onValueChange: setUnit },
        ]}
      />
      <Text style={{ textAlign: 'center' }} color="textSecondary">
        Every {every === 1 ? '' : `${every} `}{plural(unit)} · next on {next.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' })}
      </Text>
    </Box>
  );
}
```

## Columns

Each entry in `columns` is a `WheelPicker`'s props (minus the shared ones below) plus layout keys:

```ts
type WheelColumn<T> = Omit<WheelPickerProps<T>, 'itemHeight' | 'visibleItems' | 'variant' | 'showIndicator' | 'theme'> & {
  key: string;     // React key, required
  flex?: number;   // flex weight, default 1
  width?: number;  // fixed width instead of flex
  suffix?: string; // text after the column at the selection band, such as a unit
};
```

So every column has its own `items`, `value`, `onValueChange`, `onValueChanging`, `loop`, `renderItem`, `keyboardInput`, `isEqual`, `textAlign`, `disabled`, `styles` and so on. `itemHeight`, `visibleItems`, `variant` and `theme` are set once on the `MultiWheelPicker` so all columns line up.

## Labels and separators

`separator` is placed between every pair of columns. A string is rendered as bold text (style it with the `separator` slot), and any React node is rendered as-is. Pass a function to choose per gap: it gets the index of the column on the left and can return `null` to skip that gap.

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

const feet = [3, 4, 5, 6, 7].map((v) => ({ label: `${v} ft`, value: v }));
const inches = Array.from({ length: 12 }, (_, i) => ({
  label: `${i} in`,
  value: i,
}));

export default function Example() {
  const [ft, setFt] = useState(5);
  const [inch, setInch] = useState(9);
  return (
    <>
      <MultiWheelPicker
        columns={[
          {
            key: 'ft',
            items: feet,
            value: ft,
            onValueChange: setFt,
            textAlign: 'right',
          },
          {
            key: 'in',
            items: inches,
            value: inch,
            onValueChange: setInch,
            textAlign: 'left',
          },
        ]}
      />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {ft}′{inch}″ = {Math.round((ft * 12 + inch) * 2.54)} cm
      </Text>
    </>
  );
}
```

For a unit after each column, such as `min`, set the column's `suffix` instead: it's shown after the column at the selection band in the theme's secondary text color, and the `separator` slot styles it too. [`DurationPicker`](./duration-picker) labels its wheels this way.

## Column widths

Use `flex` for proportional columns and `width` for fixed ones:

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

const amounts = Array.from({ length: 100 }, (_, i) => (i + 1) * 10);

export default function Example() {
  const [cur, setCur] = useState('USD');
  const [amount, setAmount] = useState(250);
  return (
    <MultiWheelPicker
      variant="flat"
      columns={[
        {
          key: 'cur',
          items: ['USD', 'EUR', 'GBP', 'ILS'],
          value: cur,
          onValueChange: setCur,
          width: 90,
        },
        {
          key: 'amount',
          items: amounts,
          value: amount,
          onValueChange: setAmount,
          flex: 2,
        },
      ]}
    />
  );
}
```

## Dependent columns

Columns are plain props, so derive one from another in render. Here the model list depends on the brand:

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

const models: Record<string, string[]> = {
  Apple: ['iPhone 15', 'iPhone 16', 'iPhone 17'],
  Google: ['Pixel 8', 'Pixel 9', 'Pixel 10'],
  Samsung: ['Galaxy S24', 'Galaxy S25', 'Galaxy Z Fold'],
};

export default function Example() {
  const [brand, setBrand] = useState('Google');
  const [model, setModel] = useState('Pixel 9');
  return (
    <MultiWheelPicker
      columns={[
        {
          key: 'brand',
          items: Object.keys(models),
          value: brand,
          onValueChange: (b) => {
            setBrand(b);
            setModel(models[b][0]);
          },
        },
        {
          key: 'model',
          items: models[brand],
          value: model,
          onValueChange: setModel,
          flex: 1.4,
        },
      ]}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `WheelColumn[]` | **required** | One entry per wheel; see [Columns](#columns). |
| `separator` | `ReactNode \| ((leftIndex: number) => ReactNode)` | — | Content between columns. Strings use the `separator` slot style. |
| `itemHeight` | `number` | `40` | Row height shared by all columns. |
| `visibleItems` | `number` | `5` | Visible rows (odd) shared by all columns. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style for all columns. |
| `style` | `StyleProp<ViewStyle>` | — | Outer container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | Slot styles, applied to every column (a column's own `styles` win). |
| `theme` | `DeepPartial<Theme>` | — | Theme override for all columns. |
| `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 on the container. |

### Slots

| Slot | Element |
| --- | --- |
| `container` | Outer view |
| `indicator` | The shared selection band |
| `separator` | String separators |
| `item`, `itemText`, `selectedItemText`, `disabledItemText` | Forwarded to every column's wheel |

```ts
type MultiWheelSlot = 'container' | 'indicator' | 'separator' | WheelPickerSlot;
```

## Related

- [TimePicker](./time-picker), [DurationPicker](./duration-picker) and [DateWheelPicker](./date-wheel-picker) use `MultiWheelPicker` for their wheels
- [Workout timer example](/examples/workout-timer)
