/// Inputs

MonthPicker

Inline 12-month grid with a year header for navigation and full arrow-key selection, returning the first day of the chosen month.

import { MonthPicker } from "@protocore/pds";

View as Markdown

Basics

Twelve month cells sit under a year header; the chevrons move the view year. Selecting a month emits a Date normalised to its first day. Controllable via value / defaultValue / onValueChange plus a controllable view year.

2026

Bounded range

Pass min / max to disable months outside the valid window — disabled cells stay keyboard-reachable but can't be selected.

2026

When to use it

Use MonthPicker when the unit is a whole month — a billing period, a report month — and a day grid would be needless precision. For a year alone use YearPicker; when a specific day matters use DatePicker or Calendar.

Usage

Treat the emitted `Date` as a month — read its year and month, ignore the day.
Set `min` / `max` to the selectable window so out-of-range months disable.
Pass a `locale` and choose `monthFormat` (`short` / `long`) to fit the space.
Wrap it in a `Field` when it needs a visible label.

Don't

Don't use it when the day within the month actually matters — reach for Calendar.
Don't infer selection from the header year — read `onValueChange`.
Don't hand it into a popover expecting a trigger; it renders inline.
Don't rely on colour alone — the selected cell also inverts its fill.

Accessibility

Keys	Action
`Arrow keys`	Move between month cells (clamped to the grid).
`Home / End`	Jump to the first / last month cell.
`Enter / Space`	Select the focused month.

The month cells form a `role="grid"` with `role="row"` groupings and roving tabindex, so only one cell is in the tab order.
Each cell carries an `aria-label` of its full month and year and `aria-selected` when chosen.
The year header exposes labelled Previous / Next buttons and an `aria-live` year readout.

`MonthPicker` props

Prop	Type	Default	Description
`className`	`string`	—
`defaultValue`	`Date \| null`	—	Initial selected month in uncontrolled mode.
`defaultYear`	`number`	—	Initial view year in uncontrolled mode.
`locale`	`string`	—	BCP-47 locale for month labels.
`max`	`Date`	—	Latest selectable month (inclusive).
`min`	`Date`	—	Earliest selectable month (inclusive).
`monthFormat`	`enum`	`short`	Month label style.
`onValueChange`	`((value: Date) => void)`	—	Fires with the first day of the chosen month.
`onYearChange`	`((year: number) => void)`	—	Fires when the view year changes via navigation.
`style`	`CSSProperties`	—
`value`	`Date \| null`	—	Controlled selected month (any day within it; normalised to the 1st).
`year`	`number`	—	Controlled view year.