Skip to content

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

InputsReact

Year Calendar

A page of twelve years for choosing a year, or several with multiple.

Rendered by React 19.3.1

Loading React…
import { Field } from '@hamur/react/field'
import { YearCalendar } from '@hamur/react/year-calendar'

export default function YearCalendarExample() {
  return (
    <Field.Root name="graduation" className="field">
      <Field.Label>Graduation year</Field.Label>
      <YearCalendar.Root
        className="calendar"
        locale="en-US"
        today="2026-11-07"
        max="2026"
      >
        <div className="calendar-header">
          <YearCalendar.PrevButton className="calendar-nav">
            ‹
          </YearCalendar.PrevButton>
          <YearCalendar.Heading className="calendar-heading" />
          <YearCalendar.NextButton className="calendar-nav">
            ›
          </YearCalendar.NextButton>
        </div>
        <YearCalendar.YearGrid className="calendar-grid">
          {(grid) => (
            <YearCalendar.GridBody>
              {grid.rows.map((row, index) => (
                <YearCalendar.GridRow key={index}>
                  {row.map((cell) => (
                    <YearCalendar.Cell
                      key={cell.year}
                      year={cell.year}
                      className="calendar-cell calendar-period-cell"
                    >
                      <YearCalendar.Year className="calendar-period" />
                    </YearCalendar.Cell>
                  ))}
                </YearCalendar.GridRow>
              ))}
            </YearCalendar.GridBody>
          )}
        </YearCalendar.YearGrid>
      </YearCalendar.Root>
    </Field.Root>
  )
}
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:

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

Examples

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

API reference

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

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

GridBodyYearCalendar.GridBody

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

GridRowYearCalendar.GridRow

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

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

NextButtonYearCalendar.NextButton

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

PrevButtonYearCalendar.PrevButton

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

RootYearCalendar.Root

Groups all parts of a calendar that selects one year, or several with multiple. Values are '2026' strings, shown a page of yearsPerPage years at a time. 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
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 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 year, null for none.YearCalendarInputValue<Multiple> | null—
defaultValueThe selected year when initially rendered.YearCalendarInputValue<Multiple> | null—
onValueChangeEvent handler called when the selection changes.((value: YearCalendarOutputValue<Multiple>, eventDetails: CalendarRootChangeEventDetails) => void)—
multipleWhether several years 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.

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

YearGridYearCalendar.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 year; past the page it shows the next or previous pageCell
ArrowUpArrowDownMoves focus a row of years (columns, four by default)Cell
HomeEndMoves focus to the first or last year of the row; with Control, of the pageCell
PageUpPageDownMoves a page of years; with Shift, ten pagesCell
Focuses the year whose digits are typed in one burstCell
EnterSpaceSelects the focused year; with multiple, toggles itCell

Accessibility

What the parts set
PartSetsSo that
Rootrole="group", named by aria-label or Field.Label; data-view="year"the calendar is one named control
Headingthe page, "2020 – 2031"; aria-live="polite" and aria-atomica new page is announced when the buttons or the keys change it
YearGridrole="grid" labelled by its Heading; no header rowthe grid is read by its page
Cellrole="gridcell", roving tabindex, aria-selected, aria-disabled, aria-current="date", aria-label the yearit is read "2026, current year, selected"
Yearthe year as text in the locale's digits, no rolethe number only styles; the cell carries the name
PrevButton"Previous years" and "Next years", aria-disabled at the bound, never disabledthe buttons keep focus at min or max and say they do nothing

Focus order

  1. PrevButton and NextButton, in the order you render them.
  2. The grid is one tab stop: the year that last had focus, else the selected year, else this year, else the first enabled year. Nothing takes focus on mount.
  3. Tab leaves the grid.