Skip to content

Year Picker

Select one or more years from a grid.

Demos

Size
2026 – 2037

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Installation

Complete the shared installation. Copy YearPicker.vue and index.ts into app/components/ui/year-picker/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

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.

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.

Events

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.

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.