InputsReact
A grid of the twelve months of a year for choosing a month, or several with multiple.
Rendered by React 19.3.1
Loading React…Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<MonthCalendar.Root>
<MonthCalendar.PrevButton />
<MonthCalendar.Heading />
<MonthCalendar.ViewTrigger />
<MonthCalendar.NextButton />
<MonthCalendar.MonthGrid>
<MonthCalendar.GridBody>
<MonthCalendar.GridRow>
<MonthCalendar.Cell>
<MonthCalendar.Month />
</MonthCalendar.Cell>
</MonthCalendar.GridRow>
</MonthCalendar.GridBody>
</MonthCalendar.MonthGrid>
<MonthCalendar.YearGrid>
<MonthCalendar.Year />
</MonthCalendar.YearGrid>
</MonthCalendar.Root>Examples
Multiple
multiple toggles months and reports them in ascending order; maxSelected stops at four.
Limits
min and max disable the months outside November 2026 to October 2027; isMonthUnavailable keeps July and August from being chosen.
API reference
41 props across 12 parts, in React syntax. className, style, render are listed once, under Shared props.
CellMonthCalendar.Cell
A cell of a grid, and the focus holder of its date, month or year (APG): it is the roving tab stop, carries aria-selected, aria-disabled and aria-current, is named by the full value, and is pressed by click, Enter and Space. It takes exactly one of date, month and year, the unit of its grid. Put a Calendar.Day, Calendar.Month or Calendar.Year inside for styling. Renders a <td>.
| Prop | Type | Default |
|---|---|---|
dateThe date of the cell, '2026-11-07'. | `${number}-${number}-${number}` | — |
monthThe month of the cell, '2026-11'. | `${number}-${number}` | — |
yearThe year of the cell, '2026'. | `${number}` | — |
| Data attribute | Description |
|---|---|
data-selected | Present when the date is selected (every date of a selected range). |
data-today | Present on today's date. |
data-disabled | Present when the date cannot be focused or chosen: before min, after max, or disabled. |
data-unavailable | Present when the date can be focused but not chosen (isDateUnavailable). |
data-outside-month | Present on a date that belongs to the previous or the next month. |
data-weekend | Present on a date of the locale's weekend. |
data-highlighted | Present when the date has focus. |
data-range-start | Range: present on the first date of the selected range. |
data-range-end | Range: present on the last date of the selected range. |
data-in-range | Range: present on a date between the ends of the selected range. |
data-preview | Range: present on the dates of the pending range (anchor to hovered or focused date). |
data-preview-start | Range: present on the first date of the pending range. |
data-preview-end | Range: present on the last date of the pending range. |
data-current | Present on the current month or year. |
data-has-selection | Present on a month or year that shows a finer view and holds a selected value. |
data-value | The cell's value: a date, a month or a year. |
GridBodyMonthCalendar.GridBody
The body of a grid: the rows of weeks. Renders a <tbody>.
GridRowMonthCalendar.GridRow
A row of a grid: a week, or the row of weekday names. Renders a <tr>.
HeadingMonthCalendar.Heading
The name of a visible month, for example "November 2026", and the label of its grid. The first one is a polite live region, so a screen reader announces a new month. Renders a <h2>.
| Prop | Type | Default |
|---|---|---|
offsetWhich of the visible months this heading names: 0 is the first. | number | 0 |
MonthMonthCalendar.Month
The content of a month Calendar.Cell: the short month name, for styling. It is presentational (no role, no tab stop): the cell holds focus and the state. It carries the same data-* attributes as the cell, and none inside a Cell of another unit. Renders a <span>.
| Data attribute | Description |
|---|---|
data-selected | Present when the month is selected (every month of a selected range). |
data-current | Present on the current month. |
data-disabled | Present when the month cannot be focused or chosen: outside min and max, or disabled. |
data-unavailable | Present when the month can be focused but not chosen. |
data-highlighted | Present when the month has focus. |
data-range-start | Range: present on the first month of the selected range. |
data-range-end | Range: present on the last month of the selected range. |
data-in-range | Range: present on a month between the ends of the selected range. |
data-preview | Range: present on the months of the pending range (anchor to hovered or focused month). |
data-preview-start | Range: present on the first month of the pending range. |
data-preview-end | Range: present on the last month of the pending range. |
data-has-selection | Present on a month that shows a finer view and holds a selected value. |
MonthGridMonthCalendar.MonthGrid
The grid of the months of one year. Its children are a function of the year: rows (the months of each row, columns long), year and label. It renders only while the month view is shown, and never in a year calendar. Renders a <table>.
| Prop | Type | Default |
|---|---|---|
offsetWhich of the visible years this grid shows: 0 is the first. | number | 0 |
childrenThe content, or a function of the year's rows of months. | React.ReactNode | ((grid: CalendarMonthGridData) => React.ReactNode) | — |
NextButtonMonthCalendar.NextButton
Shows the next month(s). It is aria-disabled, not disabled, at the max bound, so it keeps focus. Renders a <button>.
PrevButtonMonthCalendar.PrevButton
Shows the previous month(s). It is aria-disabled, not disabled, at the min bound, so it keeps focus. Renders a <button>.
RootMonthCalendar.Root
Groups all parts of a calendar that selects one month, or several with multiple. Values are '2026-11' strings. A press on a year of the year view shows that year's months. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
viewThe view shown. | "month" | "year" | — |
onViewChangeEvent handler called when the view changes: a ViewTrigger press, or a press on a month or a | ((view: "month" | "year", eventDetails: CalendarRootViewChangeEventDetails) => void) | — |
viewsThe views the user can reach, in any order. | readonly ("month" | "year")[] | — |
columnsThe number of cells in a row of a month or year grid, and the step of ArrowUp and ArrowDown | number | 4 |
yearsPerPageThe number of years a year grid shows. | number | 12 |
disabledWhether the component should ignore user interaction. | boolean | false |
readOnlyWhether the user should be unable to change the selection. | boolean | false |
requiredWhether the user must choose a date before submitting a form. | boolean | false |
nameIdentifies the field when a form is submitted. | string | — |
formIdentifies the form that owns the hidden input. | string | — |
localeThe BCP 47 locale of the month names, weekday names, digits and first day of the week. | string | 'en-US' |
timeZoneThe time zone that decides what today is, when today is not given. | string | — |
disallowEmptySelectionWhether the last selected value cannot be deselected. | boolean | false |
maxSelectedmultiple only: the most values that can be selected. | number | — |
labelsThe texts the calendar adds: the Previous and Next labels and the words after a cell's name. | Partial<CalendarLabels> | — |
inputRefA ref to access the hidden input element. | React.Ref<HTMLInputElement> | — |
minThe earliest month that can be focused or chosen: a date, a month or a year. | `${number}` | `${number}-${number}-${number}` | `${number}-${number}` | — |
maxThe latest month that can be focused or chosen: a date, a month or a year. | `${number}` | `${number}-${number}-${number}` | `${number}-${number}` | — |
isMonthUnavailableWhether a month can be focused but not chosen. | ((month: `${number}-${number}`, anchor: `${number}-${number}` | null) => boolean) | — |
isMonthDisabledWhether a month is disabled: navigation skips it and it cannot be chosen. | ((month: `${number}-${number}`) => boolean) | — |
defaultViewThe view shown when initially rendered. | "month" | "year" | 'month' |
visibleYearThe first visible year. | `${number}` | null | — |
defaultVisibleYearThe first visible year when initially rendered. | `${number}` | — |
onVisibleYearChangeEvent handler called when the visible year changes. | ((year: `${number}`, eventDetails: CalendarRootVisibleYearChangeEventDetails) => void) | — |
visibleYearsThe number of years shown side by side. | number | 1 |
pageBehaviorWhether Previous and Next move by every visible year or by one. | CalendarPageBehavior | 'visible' |
todayThe date that decides the current month. | `${number}-${number}-${number}` | `${number}-${number}` | — |
highlightedMonthThe month that holds focus. | `${number}-${number}` | null | — |
onHighlightChangeEvent handler called when the focused month changes. | ((month: `${number}-${number}` | null) => void) | — |
valueThe selected month, null for none. | MonthCalendarInputValue<Multiple> | null | — |
defaultValueThe selected month when initially rendered. | MonthCalendarInputValue<Multiple> | null | — |
onValueChangeEvent handler called when the selection changes. | ((value: MonthCalendarOutputValue<Multiple>, eventDetails: CalendarRootChangeEventDetails) => void) | — |
multipleWhether several months can be selected. | Multiple | false |
| Data attribute | Description |
|---|---|
data-disabled | Present when the calendar is disabled. |
data-readonly | Present when the calendar does not allow changing the selection. |
data-required | Present when the calendar is required. |
data-multiple | Present when the calendar allows several selected dates. |
data-range | Present in a range calendar. |
data-empty | Present when nothing is selected. |
data-view | The view shown: day, month or year. |
ViewTriggerMonthCalendar.ViewTrigger
Shows the next coarser view, and from the coarsest the finest: day, month, year. It is named by the heading and what a press shows ("November 2026, choose month"). It renders nothing in a year calendar. Renders a <button>.
| Data attribute | Description |
|---|---|
data-view | The view shown: day, month or year. |
data-disabled | Present when the calendar is disabled. |
YearMonthCalendar.Year
The content of a year Calendar.Cell: the year in the locale's digits, for styling. It is presentational (no role, no tab stop): the cell holds focus and the state. It carries the same data-* attributes as the cell, and none inside a Cell of another unit. Renders a <span>.
| Data attribute | Description |
|---|---|
data-selected | Present when the year is selected (every year of a selected range). |
data-current | Present on the current year. |
data-disabled | Present when the year cannot be focused or chosen: outside min and max, or disabled. |
data-unavailable | Present when the year can be focused but not chosen. |
data-highlighted | Present when the year has focus. |
data-range-start | Range: present on the first year of the selected range. |
data-range-end | Range: present on the last year of the selected range. |
data-in-range | Range: present on a year between the ends of the selected range. |
data-preview | Range: present on the years of the pending range (anchor to hovered or focused year). |
data-preview-start | Range: present on the first year of the pending range. |
data-preview-end | Range: present on the last year of the pending range. |
data-has-selection | Present on a year that shows a finer view and holds a selected value. |
YearGridMonthCalendar.YearGrid
The grid of one page of years. Its children are a function of the page: rows (the years of each row, columns long), first, last and label. It renders only while the year view is shown. Renders a <table>.
| Prop | Type | Default |
|---|---|---|
offsetWhich of the visible pages this grid shows: 0 is the first. | number | 0 |
childrenThe content, or a function of the page's rows of years. | React.ReactNode | ((grid: CalendarYearGridData) => React.ReactNode) | — |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| ArrowLeftArrowRight | Moves focus a month; past December or January it shows the next or previous year | Cell |
| ArrowUpArrowDown | Moves focus a row of months (columns, four by default) | Cell |
| HomeEnd | Moves focus to the first or last month of the row; with Control, of the shown years | Cell |
| PageUpPageDown | Moves a year, keeping the month; with Shift, ten years | Cell |
| Focuses the next month whose name starts with the letters typed in one burst | Cell | |
| EnterSpace | Selects the focused month; with multiple, toggles it; an unavailable one is not chosen | Cell |
| EnterSpace | On the caption button: shows the years, then the months again | ViewTrigger |
| EnterSpace | On a year: shows its months with focus on the same month | Year |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | role="group", named by aria-label or Field.Label; data-view | the calendar is one named control |
| Heading | the year (or the page, "2020 – 2031", in the year view); aria-live="polite" and aria-atomic on the first one | a new year is announced when the buttons or the keys change it |
| MonthGrid | a table with role="grid" labelled by its Heading, aria-multiselectable with multiple; no header row | the grid is read by its year; there are no weekdays to head columns with |
| Cell | role="gridcell", roving tabindex, aria-selected, aria-disabled, aria-current="date", aria-label the full month | it is read "November 2026, current month, selected" |
| Month | the short standalone month name as text, no role | the cell's name already holds the full month and year |
| ViewTrigger | a button named "2026, choose year" or "2020 – 2031, choose month"; data-view | the button says what the caption is and what a press shows |
| PrevButton | "Previous year" and "Next year" (in the year view, "Previous years"), aria-disabled at the bound, never disabled | the buttons keep focus at min or max and say they do nothing |
Focus order
PrevButton, theViewTriggerandNextButton, in the order you render them.- The grid is one tab stop: the month that last had focus, else the selected month, else this month, else the first enabled month. Nothing takes focus on mount.
- A press on the
ViewTriggerkeeps focus on it and renames it; a press on a year moves focus to its month. Tableaves the grid.