# React Native Date Wheel Picker

> React Native date wheel picker (day / month / year) with locale-aware column order, min/max dates and day clamping. Ideal for birthdays. Zero native code.

# DateWheelPicker

`DateWheelPicker` is a React Native date wheel picker with day, month and year wheels, like the classic iOS date picker. Best for dates far from today (birthdays, expiry dates) where a calendar would need many taps.

```tsx
import { DateWheelPicker } from 'patine-ui';
// or: <DatePicker display="wheel" … />
```

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

export default function Example() {
  const [birthday, setBirthday] = useState(new Date(1990, 4, 17));
  return (
    <>
      <DateWheelPicker
        value={birthday}
        onValueChange={setBirthday}
        maxDate={new Date()}
      />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>
        {formatDate(birthday, undefined, { dateStyle: 'long' })}
      </Text>
    </>
  );
}
```

`<DatePicker display="wheel" />` renders exactly this component with the same props.

## Example: date of birth at sign-up

A sign-up form for a service with an age limit: the wheels can't go past today, the age shows as you turn them, and Continue waits until the person is 18.

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

const ageOn = (birth: Date, today: Date) =>
  today.getFullYear() - birth.getFullYear() - (today < new Date(today.getFullYear(), birth.getMonth(), birth.getDate()) ? 1 : 0);

export default function Example() {
  const today = new Date();
  const [birthday, setBirthday] = useState(new Date(today.getFullYear() - 16, 6, 9));
  const age = ageOn(birthday, today);
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 380 }}>
      <VStack gap="xs">
        <Text weight="semibold">When were you born?</Text>
        <Text size="sm" color="textSecondary">You need to be 18 or older to open an account.</Text>
      </VStack>
      <DateWheelPicker value={birthday} onValueChange={setBirthday} maxDate={today} yearRange={[today.getFullYear() - 100, today.getFullYear()]} />
      <Text style={{ textAlign: 'center' }} color={age < 18 ? 'danger' : 'textSecondary'}>
        {formatDate(birthday, undefined, { dateStyle: 'long' })} · {age < 18 ? `${age}, too young for now` : `${age} years old`}
      </Text>
      <Button disabled={age < 18}>Continue</Button>
    </Box>
  );
}
```

## Column order from the locale

The order of the wheels follows the locale's date format: month / day / year for `en-US`, day / month / year for `en-GB`, `de`, `he`, `fr`, and year / month / day for `ja`, `zh`, `ko`. Override it with `order`.

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

export default function Example() {
  const [d, setD] = useState(new Date(2000, 0, 31));
  return (
    <View style={{ gap: 12 }}>
      <Text style={{ fontWeight: '600' }}>en-GB</Text>
      <DateWheelPicker
        value={d}
        onValueChange={setD}
        locale="en-GB"
        visibleItems={3}
      />
      <Text style={{ fontWeight: '600' }}>ja-JP</Text>
      <DateWheelPicker
        value={d}
        onValueChange={setD}
        locale="ja-JP"
        visibleItems={3}
      />
      <Text style={{ fontWeight: '600' }}>Custom order, numeric months</Text>
      <DateWheelPicker
        value={d}
        onValueChange={setD}
        order={['year', 'month', 'day']}
        monthFormat="numeric"
        visibleItems={3}
      />
    </View>
  );
}
```

## Month format

| `monthFormat` | Example |
| --- | --- |
| `'long'` (default) | January |
| `'short'` | Jan |
| `'numeric'` | 01 (days are zero-padded too) |

## Day clamping

When the month or year changes to one with fewer days, the day is clamped automatically: Jan 31 → February becomes Feb 28 (or 29 in leap years). The day wheel always shows exactly the days in the selected month.

## Min, max and year range

`minDate` and `maxDate` limit the selection: days and months outside the range are disabled, and a changed date is clamped into the range. The year wheel shows `yearRange`, or 100 years either side of today, kept within `minDate`'s and `maxDate`'s years.

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

export default function Example() {
  const [expiry, setExpiry] = useState(new Date(2028, 5, 1));
  return (
    <DateWheelPicker
      value={expiry}
      onValueChange={setExpiry}
      order={['month', 'year']}
      monthFormat="numeric"
      yearRange={[2026, 2040]}
      loop={false}
    />
  );
}
```

:::tip Month + year only
Pass only the columns you need in `order`, for example `['month', 'year']` for card expiry dates. The day is kept from `value`, and clamped if needed.
:::

## Looping

The day and month wheels loop by default (`loop`); the year wheel never loops.

## In a form field

`DatePickerField` with `display="wheel"` opens these wheels in a sheet from a field, and shows the confirmed date. 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 date (controlled). Time of day is preserved. |
| `defaultValue` | `Date` | today | Initial date when uncontrolled (clamped to min/max). |
| `onValueChange` | `(date: Date) => void` | — | Fires when a wheel settles. |
| `onValueChanging` | `(date: Date) => void` | — | Fires on every tick (haptics). |
| `locale` | `string` | device | Month names and default column order. |
| `minDate` | `Date` | — | Earliest selectable date. |
| `maxDate` | `Date` | — | Latest selectable date. |
| `order` | `('day' \| 'month' \| 'year')[]` | from locale | Columns and their order. |
| `monthFormat` | `'long' \| 'short' \| 'numeric'` | `'long'` | Month labels. |
| `yearRange` | `[number, number]` | today ±100 | First and last year, kept within `minDate` / `maxDate`. |
| `loop` | `boolean` | `true` | Loop day and month wheels. |
| `itemHeight` | `number` | `40` | Row height. |
| `visibleItems` | `number` | `5` | Visible rows. |
| `variant` | `'3d' \| 'flat'` | `'3d'` | Wheel style. |
| `style` | `StyleProp<ViewStyle>` | — | Container style. |
| `styles` | `SlotStyles<MultiWheelSlot>` | — | [MultiWheelPicker slots](./multi-wheel-picker#slots). |
| `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. |

```ts
type DatePart = 'day' | 'month' | 'year';
```

## Related

- [Edit profile example, with a birthday field](/examples/edit-profile)
- [DatePickerSheet with `display="wheel"`](./picker-sheets#datepickersheet)
- [DatePickerField with `display="wheel"`](./picker-fields): the wheel behind a form field
