A grid of months to pick one, with a year header. Use it for billing periods, reports and any date where the day does not matter.
Click a month, or move with the arrow keys. onChange receives a Date on the first day of the month.
Pass value and update it in onChange.
Months outside min and max are disabled, and so are the year buttons that would lead only to them.
Month names come from Intl. Set locale and the button labels.
| Attribute | Description | Type | Accepted values | Default |
|---|---|---|---|---|
| value | selected month, to control the component | Date | null | - | - |
| initialValue | selected month at the start | Date | null | - | null |
| onChange | called with the first day of the chosen month | (month: Date) => void | - | - |
| min | first month that can be picked | Date | - | - |
| max | last month that can be picked | Date | - | - |
| locale | language of the month names | string | - | en-US |
| autoFocus | focus the month on mount | boolean | - | false |
| previousLabel | name of the previous year button | string | - | Previous year |
| nextLabel | name of the next year button | string | - | Next year |
| ... | native props, passed to the root | HTMLAttributes | 'id', 'className', ... | - |
The ref points at the root div.
The months are buttons inside a group named by the year. Each one has the full name, such as "November 2026", and aria-pressed tells which is selected. Only the focused month is in the tab order.
| Key | Action |
|---|---|
| Arrow Left and Right | Previous and next month, across years |
| Arrow Up and Down | Three months back and forward |
| Home and End | First and last month of the year |
| Page Up and Down | Same month of the previous and next year |
| Enter and Space | Pick the focused month |