MonthPicker
MonthPicker picks a month and year without a day: a card's expiry date, a report's month, a billing period, a graduation date. It looks native on each platform: month and year wheels on iOS, a grid of months under the year in Material and on the web, or the one you pick with display.
import { MonthPicker } from 'patine-ui';
<> <MonthPicker value={month} onValueChange={setMonth} /> <Text style={{ textAlign: 'center', color: '#6E685E' }}>{formatMonthYear(month)}</Text> </>
Try the props
displaymonthFormatlocale<MonthPicker
value={month}
onValueChange={setMonth}
locale="en-US"
/>
Example: a card's expiry date
A payment form: a card's expiry is a month and a year, so the picker starts at this month, goes ten years ahead, and the field shows it the way the card prints it.
<Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 380 }}> <TextField label="Card number" defaultValue="4242 4242 4242 4242" keyboardType="number-pad" /> <Text weight="medium">Expires {printed}</Text> <MonthPicker value={expiry} onValueChange={setExpiry} minDate={thisMonth} yearRange={[now.getFullYear(), now.getFullYear() + 10]} monthFormat="numeric" /> <Button>Save card</Button> </Box>
The value is the first of the month
value and onValueChange use a Date on the first day of the month, at midnight: October 2026 is new Date(2026, 9, 1). A value on another day shows its month. Read the parts with getMonth() (0–11) and getFullYear().
Wheels or a grid
Each design has its own default:
display | Default in | What it is |
|---|---|---|
'wheel' | iOS | Month and year wheels, in the order the locale writes them (year first in Japanese and Chinese), like the iOS date picker's month mode |
'grid' | Material, web | The year with arrows, above its 12 months to tap. Tap the year for a page of 12 years |
<MonthPicker value={month} onValueChange={setMonth} display="grid" />
monthFormat sets the wheel's month names: 'long' (October), 'short' (Oct) or 'numeric' (10). The grid always shows short names.
Min and max
minDate and maxDate limit the months: months outside them are disabled, and the arrows and year grid stop at their years. Any day of the month counts, so minDate={new Date()} allows the current month. The years go 100 back and 100 ahead, or set yearRange; either way they stay within minDate and maxDate.
<MonthPicker value={expiry} onValueChange={setExpiry} minDate={now} maxDate={inTenYears} monthFormat="numeric" />
In a sheet
import { MonthPickerSheet } from 'patine-ui';
<MonthPickerSheet open={open} onOpenChange={setOpen} title="Report month" value={month} onConfirm={setMonth} />
It takes the shared sheet props and the picker's, and keeps a draft until Done, like the other picker sheets.
In a form field
MonthPickerField opens the sheet and shows the confirmed month for locale, like October 2026. For a card's 10/29, pass your own displayValue.
presentationdisplay<MonthPickerField
label="Report month"
placeholder="Pick a month"
value={month}
onConfirm={setMonth}
/>
<MonthPickerField
label="Expiry"
value={expiry}
onConfirm={setExpiry}
minDate={new Date()}
displayValue={expiry ? `${String(expiry.getMonth() + 1).padStart(2, '0')}/${String(expiry.getFullYear()).slice(2)}` : ''}
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | — | Selected month (controlled): its first day. |
defaultValue | Date | this month | Initial month when uncontrolled. |
onValueChange | (month: Date) => void | — | Fires with the first day of the picked month. |
display | 'wheel' | 'grid' | from the design | Wheels (iOS) or a grid of months (Material, web). |
locale | string | device | Month names and the wheel order. |
minDate / maxDate | Date | — | Earliest and latest selectable month: any day in it. |
yearRange | [number, number] | ±100 years | Years to offer, kept within minDate / maxDate. |
monthFormat | 'long' | 'short' | 'numeric' | 'long' | Wheel month names. |
loop | boolean | true | Loop the month wheel. |
itemHeight / visibleItems / variant | 40 / 5 / '3d' | Wheel row height, rows and style. | |
style | StyleProp<ViewStyle> | — | Container style. |
styles | SlotStyles<MonthPickerSlot> | — | Wheel slots, or the grid's header, headerTitle, arrow, arrowText, gridCell and gridCellText. |
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. The wheels get ${testID}-month and -year. |
MonthPickerSheet takes these plus the sheet props and onConfirm(month). MonthPickerField takes the sheet's props plus the field props.
Related
- DatePicker: a day in a calendar
- DateWheelPicker: day, month and year wheels
- WeekStrip: a day from a week strip