Skip to content

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

InputsReact

Year Range Calendar

A page of years for choosing a first and a last year, such as model years or the years of a publication.

Rendered by React 19.3.1

Loading React…
import * as React from 'react'
import { YearRangeCalendar } from '@hamur/react/year-range-calendar'

export default function YearRangeCalendarExample() {
  const [years, setYears] = React.useState({ start: '2021', end: '2024' })
  return (
    <div className="stack">
      <YearRangeCalendar.Root
        className="calendar"
        aria-label="Model years"
        locale="en-US"
        today="2026-11-07"
        defaultValue={{ start: '2021', end: '2024' }}
        onValueChange={(next) => {
          if (next) setYears(next)
        }}
      >
        <div className="calendar-header">
          <YearRangeCalendar.PrevButton className="calendar-nav">
            ‹
          </YearRangeCalendar.PrevButton>
          <YearRangeCalendar.Heading className="calendar-heading" />
          <YearRangeCalendar.NextButton className="calendar-nav">
            ›
          </YearRangeCalendar.NextButton>
        </div>
        <YearRangeCalendar.YearGrid className="calendar-grid">
          {(grid) => (
            <YearRangeCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <YearRangeCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <YearRangeCalendar.Cell
                      key={cell.year}
                      year={cell.year}
                      className="calendar-cell calendar-period-cell"
                    >
                      <YearRangeCalendar.Year className="calendar-period" />
                    </YearRangeCalendar.Cell>
                  ))}
                </YearRangeCalendar.GridRow>
              ))}
            </YearRangeCalendar.GridBody>
          )}
        </YearRangeCalendar.YearGrid>
      </YearRangeCalendar.Root>
      <p className="muted">
        Model years: {years.start} to {years.end}
      </p>
    </div>
  )
}
Not measured yetTests passing in React
22.5 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:

<YearRangeCalendar.Root>
  <YearRangeCalendar.PrevButton />
  <YearRangeCalendar.Heading />
  <YearRangeCalendar.NextButton />
  <YearRangeCalendar.YearGrid>
    <YearRangeCalendar.GridBody>
      <YearRangeCalendar.GridRow>
        <YearRangeCalendar.Cell>
          <YearRangeCalendar.Year />
        </YearRangeCalendar.Cell>
      </YearRangeCalendar.GridRow>
    </YearRangeCalendar.GridBody>
  </YearRangeCalendar.YearGrid>
</YearRangeCalendar.Root>

Examples

The demo at the top is the one example this component has so far.

API reference

31 props across 9 parts, in React syntax. className, style, render are listed once, under Shared props.

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

GridBodyYearRangeCalendar.GridBody

The body of a grid: the rows of weeks. Renders a <tbody>.

GridRowYearRangeCalendar.GridRow

A row of a grid: a week, or the row of weekday names. Renders a <tr>.

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

NextButtonYearRangeCalendar.NextButton

Shows the next month(s). It is aria-disabled, not disabled, at the max bound, so it keeps focus. Renders a <button>.

PrevButtonYearRangeCalendar.PrevButton

Shows the previous month(s). It is aria-disabled, not disabled, at the min bound, so it keeps focus. Renders a <button>.

RootYearRangeCalendar.Root

Groups all parts of a calendar that selects a range of years. 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' strings. Renders a <div>.

Root props
PropTypeDefault
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 year that can be focused or chosen: a date, a month or a year.`${number}` | `${number}-${number}-${number}` | `${number}-${number}`—
maxThe latest year that can be focused or chosen: a date, a month or a year.`${number}` | `${number}-${number}-${number}` | `${number}-${number}`—
isYearUnavailableWhether a year can be focused but not chosen.((year: `${number}`, anchor: `${number}` | null) => boolean)—
isYearDisabledWhether a year is disabled: navigation skips it and it cannot be chosen.((year: `${number}`) => boolean)—
visibleYearThe first year of the shown page.`${number}` | null—
defaultVisibleYearThe first year of the page shown when initially rendered.`${number}`—
onVisibleYearChangeEvent handler called when the shown page changes, with its first year.((year: `${number}`, eventDetails: CalendarRootVisibleYearChangeEventDetails) => void)—
todayThe date that decides the current year.`${number}` | `${number}-${number}-${number}` | `${number}-${number}`—
highlightedYearThe year that holds focus.`${number}` | null—
onHighlightChangeEvent handler called when the focused year changes.((year: `${number}` | null) => void)—
valueThe selected range, null for none.YearRange | null—
defaultValueThe selected range when initially rendered.YearRange | null—
onValueChangeEvent handler called when a range is committed (the second press).((value: YearRange, 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.

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

YearGridYearRangeCalendar.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 the preview, to the next page when it leaves this oneCell
EscapeCancels a pending startCell
EnterSpaceShows another page and keeps a pending startPrevButton

Accessibility

What the parts set
PartSetsSo that
Rootrole="group" named by aria-label or Field.Label; data-rangethe calendar is one named control
YearGridrole="grid" labelled by its Heading, aria-multiselectablethe years of a range are read as selected
Cellaria-selected on every year of the committed range; data-range-start, data-range-end, data-in-range, data-previewthe range is announced and styled with more than a colour

Focus order

  1. PrevButton and NextButton, in the order you render them.
  2. The grid is one tab stop: the start of the range, else this year, else the first enabled year.
  3. Tab leaves the grid; a pending start stays until it is committed or cancelled.