Year Picker

Accessible, unstyled paged grid of years.


Package	`@vizejs/ui/year-picker`
Maturity	stable
Own the source	`vize lib pull year-picker`
Requires	calendar, controllable-state, id, locale, month-picker
Aliases	year grid, decade view, year select
Covers	WAI-ARIA grid, MUI YearCalendar, React Aria year dropdown

Usage

import { YearPicker } from "@vizejs/ui/year-picker";

Or copy the source into your project with vize lib pull year-picker (see Source Distribution).

API

`YearPicker`

Source: src/families/date-time/year-picker/year-picker.vue

Props

Prop	Type	Default	Description
`id`	`string \| null \| undefined`	`undefined`	Consumer-owned base id; nullish values use a deterministic fallback.
`modelValue`	`number \| null \| undefined`	`undefined`	Controlled ISO year; `undefined` selects uncontrolled mode and `null` clears.
`defaultValue`	`number \| null \| undefined`	`null`	Initial uncontrolled year.
`min`	`number \| null \| undefined`	`undefined`	Earliest selectable year.
`max`	`number \| null \| undefined`	`undefined`	Latest selectable year.
`isYearUnavailable`	`((year: number) => boolean) \| undefined`	`undefined`	Predicate for years that stay focusable but cannot be selected.
`pageSize`	`number \| undefined`	`12`	Years per page; pages align to multiples of this size. Read once at setup.
`locale`	`string \| undefined`	`undefined`	BCP 47 locale; defaults to the nearest LocaleProvider.
`dir`	`"ltr" \| "rtl" \| undefined`	`undefined`	Text direction; defaults to the nearest LocaleProvider.
`calendar`	`string \| undefined`	`undefined`	Intl calendar used for display labels only.
`numberingSystem`	`string \| undefined`	`undefined`	Intl numbering system for labels.
`columns`	`number \| undefined`	`3`	Years per grid row.
`today`	`PlainDate \| null \| undefined`	`undefined`	Explicit current date; the SSR-safe way to mark the current year.
`now`	`DateTimeNow \| undefined`	`undefined`	Injectable clock evaluated during setup on server and client.
`timeZone`	`string \| undefined`	`undefined`	IANA time zone used with `now` and the post-mount host clock.
`disabled`	`boolean \| undefined`	`false`	Disable navigation, focus, and selection.
`readOnly`	`boolean \| undefined`	`false`	Allow navigation while blocking selection.
`name`	`string \| undefined`	`undefined`	Hidden input name that submits the year.
`previousLabel`	`string \| undefined`	`"Previous years"`	Accessible name of the previous-page control.
`nextLabel`	`string \| undefined`	`"Next years"`	Accessible name of the next-page control.
`ariaLabel`	`string \| undefined`	`undefined`	Accessible name for the picker group.
`ariaLabelledby`	`string \| undefined`	`undefined`	Ids that label the picker group; defaults to the page heading.
`ariaDescribedby`	`string \| undefined`	`undefined`	Ids that describe the picker group.

Events

Event	Payload	Description
`update:modelValue`	`[value: number \| null]`	Fired when the picker requests a new controlled year.
`change`	`[value: number \| null, previous: number \| null, nativeEvent: Event \| null]`	Fired after a distinct selection with the previous year and triggering event.
`update:focusedYear`	`[value: number]`	Fired when keyboard or navigation moves the focused year.

Slots

Slot	Slot props	Description
`heading`	`YearPickerSlotState`	Page heading content. Receives picker state.
`previous`	`YearPickerSlotState`	Previous-page control content.
`next`	`YearPickerSlotState`	Next-page control content.
`cell`	`YearPickerCellState`	Year cell content. Receives the cell state; defaults to the localized year.

Behavior

Normative state x input -> outcome table for year-picker.vue (@vizejs/ui/year-picker), a paged grid of years on the MonthPicker period grid (rows MP2–MP4 apply with pages of pageSize years instead of years of twelve months). Every row is proven by the named test.

#	State	Input	Outcome	Proven by
Y1	known	render	pages align to multiples of `pageSize` (`2016 – 2027` for 12); selected and current years are marked; `name` submits the year	`renders an aligned page of years with the current and selected year`
Y2	focused	Arrow / PageUp / PageDown	rows are `columns` wide; pages move by `pageSize`, Shift by ten pages; focus clamps to `min`/`max` and paging disables at bounds	`keyboard pages by row and page, selection emits, and bounds disable paging`
Y3	imperative	expose / predicate	`navigate`, `setValue` (scrolls to the page), `firstYear`/`lastYear`; unavailable years are marked	`exposes value and paging`
Y4	SSR	isolated requests	byte-identical markup and silent hydration	`renders byte-identical year picker markup across isolated SSR requests`, `hydrates year picker markup without mismatches`