InputsReact
A grid of months for choosing a first and a last month, such as a lease or a reporting period.
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:
<MonthRangeCalendar.Root>
<MonthRangeCalendar.PrevButton />
<MonthRangeCalendar.Heading />
<MonthRangeCalendar.NextButton />
<MonthRangeCalendar.MonthGrid>
<MonthRangeCalendar.GridBody>
<MonthRangeCalendar.GridRow>
<MonthRangeCalendar.Cell>
<MonthRangeCalendar.Month />
</MonthRangeCalendar.Cell>
</MonthRangeCalendar.GridRow>
</MonthRangeCalendar.GridBody>
</MonthRangeCalendar.MonthGrid>
</MonthRangeCalendar.Root>
// Not in this example: MonthRangeCalendar.ViewTrigger, MonthRangeCalendar.Year, MonthRangeCalendar.YearGridExamples
The demo at the top is the one example this component has so far.
API reference
39 props across 12 parts, in React syntax. className, style, render are listed once, under Shared props.
CellMonthRangeCalendar.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. |
GridBodyMonthRangeCalendar.GridBody
The body of a grid: the rows of weeks. Renders a <tbody>.
GridRowMonthRangeCalendar.GridRow
A row of a grid: a week, or the row of weekday names. Renders a <tr>.
HeadingMonthRangeCalendar.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 |
MonthMonthRangeCalendar.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. |
MonthGridMonthRangeCalendar.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) | — |
NextButtonMonthRangeCalendar.NextButton
Shows the next month(s). It is aria-disabled, not disabled, at the max bound, so it keeps focus. Renders a <button>.
PrevButtonMonthRangeCalendar.PrevButton
Shows the previous month(s). It is aria-disabled, not disabled, at the min bound, so it keeps focus. Renders a <button>.
RootMonthRangeCalendar.Root
Groups all parts of a calendar that selects a range of months. The first press sets the start, the second commits the range; arrows or the pointer preview it and Escape cancels. Values are { start, end } with '2026-11' strings. 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 |
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 range, null for none. | MonthRange | null | — |
defaultValueThe selected range when initially rendered. | MonthRange | null | — |
onValueChangeEvent handler called when a range is committed (the second press). | ((value: MonthRange, eventDetails: CalendarRootChangeEventDetails) => void) | — |
| 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. |
ViewTriggerMonthRangeCalendar.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. |
YearMonthRangeCalendar.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. |
YearGridMonthRangeCalendar.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 |
|---|---|---|
| EnterSpace | Sets the start, then commits the range, ordered when the end is earlier | Cell |
| ArrowLeftArrowRightArrowUpArrowDown | Moves focus and, with a pending start, the preview | Cell |
| Escape | Cancels a pending start; without one it is not consumed | Cell |
| EnterSpace | On the caption button: shows the years, keeping a pending start | ViewTrigger |
| HomeEndPageUpPageDown | Move as in MonthCalendar | Cell |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | role="group" named by aria-label or Field.Label; data-range | the calendar is one named control |
| MonthGrid | role="grid" labelled by its Heading, aria-multiselectable | the months of a range are read as selected |
| Cell | aria-selected on every month of the committed range | each month says whether it is in the range |
| Cell | data-range-start, data-range-end, data-in-range, data-preview | the range and its preview can be styled with more than a colour |
Focus order
PrevButton, theViewTriggerandNextButton, in the order you render them.- The grid is one tab stop: the start of the range, else this month, else the first enabled month.
- The arrow keys move focus and the preview; Escape cancels the pending start and keeps focus.
Tableaves the grid; a pending start stays until it is committed or cancelled.