Skip to content

Year Picker

Accessible paged year grid with constraints and single or multiple selection.

YearPicker presents a configurable page of years with roving focus, paging, constraints, locale formatting, and single or multiple selection. Selected values are @internationalized/date dates normalized to January 1.

Anatomy

  • #previous: Previous-page control content.
  • #heading: Visible year-range heading.
  • #next: Next-page control content.
  • #year: Year button content and state.
  • #footer: Optional content after grid.

Usage

2024 – 2035

Selected: 2028

Examples

Page size and columns

yearsPerPage controls paging distance and visible item count. columns controls the number of keyboard rows.

vue
@layer akaza-reset;
@import "tailwindcss";
@import "akaza-ui/dist/akaza-ui.css";

Multiple years

Use multiple with an array model for non-contiguous years.

vue
<template>
  <Avatar
    src="/avatar.jpg"
    alt="Jane Doe"
    text="JD"
    :delay-ms="300"
  />
</template>

Constraints

Boundaries and matcher props use complete date values but are compared at year precision.

vue
<Button
  :ui="{
    root: 'rounded-md bg-black px-3 py-2 text-white',
    spinner: 'size-4 animate-spin',
  }"
>
  Save
</Button>

Custom year content

vue
<Dialog
  :ui="{
    overlay: 'fixed inset-0 bg-black/50',
    content: 'fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6',
  }"
/>

API Reference

Models

ModelTypeDefaultDescription
v-modelCalendarDateValue | CalendarDateValue[] | undefinedundefinedSelected year(s), normalized to January 1.
v-model:placeholderCalendarDateValueselected year or todayFirst year displayed on current page.

Props

PropTypeDefaultDescription
localestring"en-US"Locale used for year labels.
dir"ltr" | "rtl""ltr"Reading direction.
calendarLabelstring"Year picker"Accessible root label.
columnsnumber3Visual grid columns.
yearsPerPagenumber12Visible years and paging distance.
multiplebooleanfalseEnables independent multiple selection.
preventDeselectbooleanfalsePrevents removing a selected year.
disabledbooleanfalseDisables paging and selection.
readOnlybooleanfalseAllows navigation but blocks selection.
initialFocusbooleanfalseFocuses selected/current year on mount.
minValue / maxValueCalendarDateValue—Selection and paging boundaries.
isYearDisabled(date) => boolean—Marks years disabled.
isYearUnavailable(date) => boolean—Marks years unavailable.
nextPage / prevPage(placeholder) => CalendarDateValuepage arithmeticReplaces default page calculation.
uiYearPickerUi—Classes for generated parts.

Emits

EventPayloadDescription
update:modelValuevalueFires after accepted selection changes.
update:placeholderdateFires after accepted page changes.
value-change(value, details)Fires before selection. details.cancel() prevents update.
placeholder-change(date, details)Fires before paging. details.cancel() prevents update.

Slots

SlotPropsDescription
previousdisabledPrevious control content.
headinglabel, itemsVisible year-range heading.
nextdisabledNext control content.
yeardate, label, selected, today, disabled, unavailable, focusedYear button content and state.
footervalue, placeholderOptional content after grid.

Methods

MethodDescription
focusValue(date)Moves roving focus to a year and pages when needed.
selectValue(date, event?)Requests year selection.
nextPage(event?)Requests the next year page.
previousPage(event?)Requests the previous year page.

UI Options

KeyPart
rootRoot group.
headerNavigation header.
previousPrevious-page button.
headingLive year-range heading.
nextNext-page button.
gridARIA year grid.
gridRowGrid row.
cellGrid cell.
cellTriggerInteractive year button.
footerOptional footer.

Styling Hooks

UI keyCSS classData attributes
root.akaza-year-pickerdata-akaza-state, data-akaza-selection-mode, data-akaza-disabled, data-akaza-readonly, data-akaza-invalid
header.akaza-year-picker-header—
previous.akaza-year-picker-previousdata-akaza-disabled
heading.akaza-year-picker-heading—
next.akaza-year-picker-nextdata-akaza-disabled
grid.akaza-year-picker-grid—
gridRow.akaza-year-picker-grid-row—
cell.akaza-year-picker-cellSelection and availability attributes listed below.
cellTrigger.akaza-year-picker-cell-triggerdata-akaza-state, data-akaza-selected, data-akaza-today, data-akaza-disabled, data-akaza-unavailable
footer.akaza-year-picker-footer—

Keyboard

KeyBehavior
ArrowLeft / ArrowRightMoves one year, reversed in RTL.
ArrowUp / ArrowDownMoves one visual row.
Home / EndMoves to row boundary.
PageUp / PageDownMoves one yearsPerPage page.
Shift + PageUp / Shift + PageDownMoves ten pages.
Enter / SpaceSelects focused year.
Edit this page on GitHub ↗