Skip to main content

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';
Loading…
<>
  <MonthPicker value={month} onValueChange={setMonth} />
  <Text style={{ textAlign: 'center', color: '#6E685E' }}>{formatMonthYear(month)}</Text>
</>

Try the props​

Props
display
monthFormat
locale
<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.

Loading…
<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:

displayDefault inWhat it is
'wheel'iOSMonth 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, webThe 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.

Loading…
<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.

Behaves like
Props
presentation
display
<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)}` : ''}
/>

→ Picker fields

Props​

PropTypeDefaultDescription
valueDate—Selected month (controlled): its first day.
defaultValueDatethis monthInitial month when uncontrolled.
onValueChange(month: Date) => void—Fires with the first day of the picked month.
display'wheel' | 'grid'from the designWheels (iOS) or a grid of months (Material, web).
localestringdeviceMonth names and the wheel order.
minDate / maxDateDate—Earliest and latest selectable month: any day in it.
yearRange[number, number]±100 yearsYears to offer, kept within minDate / maxDate.
monthFormat'long' | 'short' | 'numeric''long'Wheel month names.
loopbooleantrueLoop the month wheel.
itemHeight / visibleItems / variant40 / 5 / '3d'Wheel row height, rows and style.
styleStyleProp<ViewStyle>—Container style.
stylesSlotStyles<MonthPickerSlot>—Wheel slots, or the grid's header, headerTitle, arrow, arrowText, gridCell and gridCellText.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow, over the provider's: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—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.