Skip to content

Early previewhamur is not on npm yet. The components are being built in the open, follow along on GitHub.

InputsReact

Month Range Calendar

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…
import * as React from 'react'
import { MonthRangeCalendar } from '@hamur/react/month-range-calendar'

export default function MonthRangeCalendarExample() {
  const [lease, setLease] = React.useState({ start: '2026-03', end: '2026-06' })
  return (
    <div className="stack">
      <MonthRangeCalendar.Root
        className="calendar"
        aria-label="Lease"
        locale="en-US"
        today="2026-11-07"
        defaultValue={{ start: '2026-03', end: '2026-06' }}
        onValueChange={(next) => {
          if (next) setLease(next)
        }}
      >
        <div className="calendar-header">
          <MonthRangeCalendar.PrevButton className="calendar-nav">
            ‹
          </MonthRangeCalendar.PrevButton>
          <MonthRangeCalendar.Heading className="calendar-heading" />
          <MonthRangeCalendar.NextButton className="calendar-nav">
            ›
          </MonthRangeCalendar.NextButton>
        </div>
        <MonthRangeCalendar.MonthGrid className="calendar-grid">
          {(grid) => (
            <MonthRangeCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <MonthRangeCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <MonthRangeCalendar.Cell
                      key={cell.month}
                      month={cell.month}
                      className="calendar-cell calendar-period-cell"
                    >
                      <MonthRangeCalendar.Month className="calendar-period" />
                    </MonthRangeCalendar.Cell>
                  ))}
                </MonthRangeCalendar.GridRow>
              ))}
            </MonthRangeCalendar.GridBody>
          )}
        </MonthRangeCalendar.MonthGrid>
      </MonthRangeCalendar.Root>
      <p className="muted">
        Lease: {lease.start} to {lease.end}
      </p>
    </div>
  )
}
Not measured yetTests passing in React
22.9 KiBSize
Not measured yetMemory
Not measured yetSpeed
[N] commits

Installation

npm i @hamur/react

Not 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.YearGrid

Examples

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

Cell props
PropTypeDefault
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}`—
Cell data attributes
Data attributeDescription
data-selectedPresent when the date is selected (every date of a selected range).
data-todayPresent on today's date.
data-disabledPresent when the date cannot be focused or chosen: before min, after max, or disabled.
data-unavailablePresent when the date can be focused but not chosen (isDateUnavailable).
data-outside-monthPresent on a date that belongs to the previous or the next month.
data-weekendPresent on a date of the locale's weekend.
data-highlightedPresent when the date has focus.
data-range-startRange: present on the first date of the selected range.
data-range-endRange: present on the last date of the selected range.
data-in-rangeRange: present on a date between the ends of the selected range.
data-previewRange: present on the dates of the pending range (anchor to hovered or focused date).
data-preview-startRange: present on the first date of the pending range.
data-preview-endRange: present on the last date of the pending range.
data-currentPresent on the current month or year.
data-has-selectionPresent on a month or year that shows a finer view and holds a selected value.
data-valueThe 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>.

Heading props
PropTypeDefault
offsetWhich of the visible months this heading names: 0 is the first.number0

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

Month data attributes
Data attributeDescription
data-selectedPresent when the month is selected (every month of a selected range).
data-currentPresent on the current month.
data-disabledPresent when the month cannot be focused or chosen: outside min and max, or disabled.
data-unavailablePresent when the month can be focused but not chosen.
data-highlightedPresent when the month has focus.
data-range-startRange: present on the first month of the selected range.
data-range-endRange: present on the last month of the selected range.
data-in-rangeRange: present on a month between the ends of the selected range.
data-previewRange: present on the months of the pending range (anchor to hovered or focused month).
data-preview-startRange: present on the first month of the pending range.
data-preview-endRange: present on the last month of the pending range.
data-has-selectionPresent 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>.

MonthGrid props
PropTypeDefault
offsetWhich of the visible years this grid shows: 0 is the first.number0
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>.

Root props
PropTypeDefault
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 ArrowDownnumber4
yearsPerPageThe number of years a year grid shows.number12
disabledWhether the component should ignore user interaction.booleanfalse
readOnlyWhether the user should be unable to change the selection.booleanfalse
requiredWhether the user must choose a date before submitting a form.booleanfalse
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.booleanfalse
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.number1
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)—
Root data attributes
Data attributeDescription
data-disabledPresent when the calendar is disabled.
data-readonlyPresent when the calendar does not allow changing the selection.
data-requiredPresent when the calendar is required.
data-multiplePresent when the calendar allows several selected dates.
data-rangePresent in a range calendar.
data-emptyPresent when nothing is selected.
data-viewThe 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>.

ViewTrigger data attributes
Data attributeDescription
data-viewThe view shown: day, month or year.
data-disabledPresent 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>.

Year data attributes
Data attributeDescription
data-selectedPresent when the year is selected (every year of a selected range).
data-currentPresent on the current year.
data-disabledPresent when the year cannot be focused or chosen: outside min and max, or disabled.
data-unavailablePresent when the year can be focused but not chosen.
data-highlightedPresent when the year has focus.
data-range-startRange: present on the first year of the selected range.
data-range-endRange: present on the last year of the selected range.
data-in-rangeRange: present on a year between the ends of the selected range.
data-previewRange: present on the years of the pending range (anchor to hovered or focused year).
data-preview-startRange: present on the first year of the pending range.
data-preview-endRange: present on the last year of the pending range.
data-has-selectionPresent 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>.

YearGrid props
PropTypeDefault
offsetWhich of the visible pages this grid shows: 0 is the first.number0
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.

Shared props
PropType
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

Keyboard
KeysDoesPart
EnterSpaceSets the start, then commits the range, ordered when the end is earlierCell
ArrowLeftArrowRightArrowUpArrowDownMoves focus and, with a pending start, the previewCell
EscapeCancels a pending start; without one it is not consumedCell
EnterSpaceOn the caption button: shows the years, keeping a pending startViewTrigger
HomeEndPageUpPageDownMove as in MonthCalendarCell

Accessibility

What the parts set
PartSetsSo that
Rootrole="group" named by aria-label or Field.Label; data-rangethe calendar is one named control
MonthGridrole="grid" labelled by its Heading, aria-multiselectablethe months of a range are read as selected
Cellaria-selected on every month of the committed rangeeach month says whether it is in the range
Celldata-range-start, data-range-end, data-in-range, data-previewthe range and its preview can be styled with more than a colour

Focus order

  1. PrevButton, the ViewTrigger and NextButton, in the order you render them.
  2. The grid is one tab stop: the start of the range, else this month, else the first enabled month.
  3. The arrow keys move focus and the preview; Escape cancels the pending start and keeps focus.
  4. Tab leaves the grid; a pending start stays until it is committed or cancelled.