Skip to content

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

InputsReact

Month Calendar

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…
import { Field } from '@hamur/react/field'
import { MonthCalendar } from '@hamur/react/month-calendar'

export default function MonthCalendarExample() {
  return (
    <Field.Root name="billing" className="field">
      <Field.Label>Billing month</Field.Label>
      <MonthCalendar.Root
        className="calendar"
        locale="en-US"
        today="2026-11-07"
        min="2026-01"
        max="2027-12"
        defaultValue="2026-11"
      >
        <div className="calendar-header">
          <MonthCalendar.PrevButton className="calendar-nav">
            ‹
          </MonthCalendar.PrevButton>
          <div className="calendar-caption">
            <MonthCalendar.Heading className="calendar-heading" />
            <MonthCalendar.ViewTrigger className="calendar-view-trigger">
              <svg width="12" height="12" viewBox="0 0 12 12" aria-hidden="true">
                <path d="M2.5 4.5 6 8l3.5-3.5" />
              </svg>
            </MonthCalendar.ViewTrigger>
          </div>
          <MonthCalendar.NextButton className="calendar-nav">
            ›
          </MonthCalendar.NextButton>
        </div>
        <MonthCalendar.MonthGrid className="calendar-grid">
          {(grid) => (
            <MonthCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <MonthCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <MonthCalendar.Cell
                      key={cell.month}
                      month={cell.month}
                      className="calendar-cell calendar-period-cell"
                    >
                      <MonthCalendar.Month className="calendar-period" />
                    </MonthCalendar.Cell>
                  ))}
                </MonthCalendar.GridRow>
              ))}
            </MonthCalendar.GridBody>
          )}
        </MonthCalendar.MonthGrid>
        <MonthCalendar.YearGrid className="calendar-grid">
          {(grid) => (
            <MonthCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <MonthCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <MonthCalendar.Cell
                      key={cell.year}
                      year={cell.year}
                      className="calendar-cell calendar-period-cell"
                    >
                      <MonthCalendar.Year className="calendar-period" />
                    </MonthCalendar.Cell>
                  ))}
                </MonthCalendar.GridRow>
              ))}
            </MonthCalendar.GridBody>
          )}
        </MonthCalendar.YearGrid>
      </MonthCalendar.Root>
    </Field.Root>
  )
}
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:

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

MonthCalendarMultiple.tsx
import * as React from 'react'
import { MonthCalendar } from '@hamur/react/month-calendar'

export default function MonthCalendarMultipleExample() {
  const [value, setValue] = React.useState<string[]>(['2026-03', '2026-06'])
  return (
    <div className="stack">
      <MonthCalendar.Root
        className="calendar"
        aria-label="Payout months"
        locale="en-US"
        today="2026-11-07"
        multiple
        maxSelected={4}
        defaultValue={['2026-03', '2026-06']}
        onValueChange={(next) => setValue(next)}
      >
        <div className="calendar-header">
          <MonthCalendar.PrevButton className="calendar-nav">‹</MonthCalendar.PrevButton>
          <MonthCalendar.Heading className="calendar-heading" />
          <MonthCalendar.NextButton className="calendar-nav">›</MonthCalendar.NextButton>
        </div>
        <MonthCalendar.MonthGrid className="calendar-grid">
          {(grid) => (
            <MonthCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <MonthCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <MonthCalendar.Cell
                      key={cell.month}
                      month={cell.month}
                      className="calendar-cell calendar-period-cell"
                    >
                      <MonthCalendar.Month className="calendar-period" />
                    </MonthCalendar.Cell>
                  ))}
                </MonthCalendar.GridRow>
              ))}
            </MonthCalendar.GridBody>
          )}
        </MonthCalendar.MonthGrid>
      </MonthCalendar.Root>
      <p className="muted">
        Selected ({value.length} of 4): {value.join(', ') || 'none'}
      </p>
    </div>
  )
}

Limits

min and max disable the months outside November 2026 to October 2027; isMonthUnavailable keeps July and August from being chosen.

MonthCalendarLimits.tsx
import * as React from 'react'
import { MonthCalendar } from '@hamur/react/month-calendar'

const isSummerBreak = (month: string) => month.endsWith('-07') || month.endsWith('-08')

export default function MonthCalendarLimitsExample() {
  const [value, setValue] = React.useState<string | null>(null)
  return (
    <div className="stack">
      <MonthCalendar.Root
        className="calendar"
        aria-label="Course start"
        aria-describedby="month-calendar-limits-rule"
        locale="en-US"
        today="2026-11-07"
        min="2026-11"
        max="2027-10"
        isMonthUnavailable={isSummerBreak}
        onValueChange={(next) => setValue(next)}
      >
        <div className="calendar-header">
          <MonthCalendar.PrevButton className="calendar-nav">‹</MonthCalendar.PrevButton>
          <MonthCalendar.Heading className="calendar-heading" />
          <MonthCalendar.NextButton className="calendar-nav">›</MonthCalendar.NextButton>
        </div>
        <MonthCalendar.MonthGrid className="calendar-grid">
          {(grid) => (
            <MonthCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <MonthCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <MonthCalendar.Cell
                      key={cell.month}
                      month={cell.month}
                      className="calendar-cell calendar-period-cell"
                    >
                      <MonthCalendar.Month className="calendar-period" />
                    </MonthCalendar.Cell>
                  ))}
                </MonthCalendar.GridRow>
              ))}
            </MonthCalendar.GridBody>
          )}
        </MonthCalendar.MonthGrid>
      </MonthCalendar.Root>
      <p id="month-calendar-limits-rule" className="muted">
        From November 2026 to October 2027. No course starts in July or August.
      </p>
      <p className="muted">Start: {value ?? 'none'}</p>
    </div>
  )
}

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

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.

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

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

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

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.

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

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)—

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

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

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

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

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.

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

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
ArrowLeftArrowRightMoves focus a month; past December or January it shows the next or previous yearCell
ArrowUpArrowDownMoves focus a row of months (columns, four by default)Cell
HomeEndMoves focus to the first or last month of the row; with Control, of the shown yearsCell
PageUpPageDownMoves a year, keeping the month; with Shift, ten yearsCell
Focuses the next month whose name starts with the letters typed in one burstCell
EnterSpaceSelects the focused month; with multiple, toggles it; an unavailable one is not chosenCell
EnterSpaceOn the caption button: shows the years, then the months againViewTrigger
EnterSpaceOn a year: shows its months with focus on the same monthYear

Accessibility

What the parts set
PartSetsSo that
Rootrole="group", named by aria-label or Field.Label; data-viewthe calendar is one named control
Headingthe year (or the page, "2020 – 2031", in the year view); aria-live="polite" and aria-atomic on the first onea new year is announced when the buttons or the keys change it
MonthGrida table with role="grid" labelled by its Heading, aria-multiselectable with multiple; no header rowthe grid is read by its year; there are no weekdays to head columns with
Cellrole="gridcell", roving tabindex, aria-selected, aria-disabled, aria-current="date", aria-label the full monthit is read "November 2026, current month, selected"
Monththe short standalone month name as text, no rolethe cell's name already holds the full month and year
ViewTriggera button named "2026, choose year" or "2020 – 2031, choose month"; data-viewthe 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 disabledthe buttons keep focus at min or max and say they do nothing

Focus order

  1. PrevButton, the ViewTrigger and NextButton, in the order you render them.
  2. 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.
  3. A press on the ViewTrigger keeps focus on it and renames it; a press on a year moves focus to its month.
  4. Tab leaves the grid.