InputsReact
A page of twelve years for choosing a year, or several with multiple.
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:
<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>.
| 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. |
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>.
| Prop | Type | Default |
|---|---|---|
offsetWhich of the visible months this heading names: 0 is the first. | number | 0 |
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>.
| Prop | Type | Default |
|---|---|---|
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 |
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. | Multiple | false |
| 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. |
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>.
| 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. |
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>.
| 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 |
|---|---|---|
| ArrowLeftArrowRight | Moves focus a year; past the page it shows the next or previous page | Cell |
| ArrowUpArrowDown | Moves focus a row of years (columns, four by default) | Cell |
| HomeEnd | Moves focus to the first or last year of the row; with Control, of the page | Cell |
| PageUpPageDown | Moves a page of years; with Shift, ten pages | Cell |
| Focuses the year whose digits are typed in one burst | Cell | |
| EnterSpace | Selects the focused year; with multiple, toggles it | Cell |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | role="group", named by aria-label or Field.Label; data-view="year" | the calendar is one named control |
| Heading | the page, "2020 – 2031"; aria-live="polite" and aria-atomic | a new page is announced when the buttons or the keys change it |
| YearGrid | role="grid" labelled by its Heading; no header row | the grid is read by its page |
| Cell | role="gridcell", roving tabindex, aria-selected, aria-disabled, aria-current="date", aria-label the year | it is read "2026, current year, selected" |
| Year | the year as text in the locale's digits, no role | the number only styles; the cell carries the name |
| PrevButton | "Previous years" and "Next years", aria-disabled at the bound, never disabled | the buttons keep focus at min or max and say they do nothing |
Focus order
PrevButtonandNextButton, in the order you render them.- 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.
Tableaves the grid.