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.
import { DateWheelPicker } from 'patine-ui';
// or: <DatePicker display="wheel" … />
<> <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.
Try the props
ordermonthFormatvariant<DateWheelPicker
value={date}
onValueChange={setDate}
order={['day', 'month', 'year']}
/>
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.
<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.
<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.
<DateWheelPicker value={expiry} onValueChange={setExpiry} order={['month', 'year']} monthFormat="numeric" yearRange={[2026, 2040]} loop={false} />
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.
presentation<DatePickerField
label="Birthday"
placeholder="Pick a date"
display="wheel"
value={date}
onConfirm={setDate}
/>
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. |
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, or 'native' for the platform's own. |
testID | string | — | Test ID. |
type DatePart = 'day' | 'month' | 'year';
Related
- Edit profile example, with a birthday field
- DatePickerSheet with
display="wheel" - DatePickerField with
display="wheel": the wheel behind a form field