# React Native Month Picker

> React Native month and year picker for card expiry dates, reports and billing periods: iOS month and year wheels, or a Material and web grid of months with a year grid. Min/max, locale month names, in a bottom sheet or a form field. Zero native code.

# 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](#wheels-or-a-grid), or the one you pick with `display`.

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

```tsx live
import { useState } from 'react';
import { Text } from 'react-native';
import { MonthPicker, formatMonthYear } from 'patine-ui';

export default function Example() {
  const [month, setMonth] = useState(new Date(2026, 9, 1));
  return (
    <>
      <MonthPicker value={month} onValueChange={setMonth} />
      <Text style={{ textAlign: 'center', color: '#6E685E' }}>{formatMonthYear(month)}</Text>
    </>
  );
}
```

## 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.

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

export default function Example() {
  const now = new Date();
  const thisMonth = new Date(now.getFullYear(), now.getMonth(), 1);
  const [expiry, setExpiry] = useState(new Date(now.getFullYear() + 3, 8, 1));
  const printed = `${String(expiry.getMonth() + 1).padStart(2, '0')} / ${String(expiry.getFullYear()).slice(2)}`;
  return (
    <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](../guides/designs) 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 |

```tsx
<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`.

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

const now = new Date();
const inTenYears = new Date(now.getFullYear() + 10, 11, 1);

export default function CardExpiry() {
  const [expiry, setExpiry] = useState(new Date(now.getFullYear() + 3, 0, 1));
  return <MonthPicker value={expiry} onValueChange={setExpiry} minDate={now} maxDate={inTenYears} monthFormat="numeric" />;
}
```

## In a sheet

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

<MonthPickerSheet open={open} onOpenChange={setOpen} title="Report month" value={month} onConfirm={setMonth} />
```

It takes the [shared sheet props](./picker-sheets#shared-props) and the picker's, and keeps a draft until **Done**, like the other [picker sheets](./picker-sheets#how-drafts-work).

## 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`.

```tsx
<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](./picker-fields)

## 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](./multi-wheel-picker#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](../guides/designs), 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](./picker-sheets#shared-props) and `onConfirm(month)`. `MonthPickerField` takes the sheet's props plus the [field props](./picker-fields#props).

## Related

- [DatePicker](./date-picker): a day in a calendar
- [DateWheelPicker](./date-wheel-picker): day, month and year wheels
- [WeekStrip](./week-strip): a day from a week strip
