Year Picker

Alpha

Presents a calendar view tailored for selecting years.

View code

2020 - 2031

2020	2021	2022	2023
2024	2025	2026	2027
2028	2029	2030	2031

Year Picker, 2020 - 2031

Features

Full keyboard navigation
Can be controlled or uncontrolled
Focus is fully managed
Localization support
Highly composable
Configurable years per page

Preface

The component depends on the @internationalized/date package, which solves a lot of the problems that come with working with dates and times in JavaScript.

We highly recommend reading through the documentation for the package to get a solid feel for how it works, and you'll need to install it in your project to use the date-related components.

Installation

Install the date package.

$ npm add @internationalized/date

Install the component from your command line.

$ npm add reka-ui

Anatomy

Import all parts and piece them together.

vue

<script setup>
import {
  YearPickerCell,
  YearPickerCellTrigger,
  YearPickerGrid,
  YearPickerGridBody,
  YearPickerGridRow,
  YearPickerHeader,
  YearPickerHeading,
  YearPickerNext,
  YearPickerPrev,
  YearPickerRoot,
} from 'reka-ui'
</script>

<template>
  <YearPickerRoot>
    <YearPickerHeader>
      <YearPickerPrev />
      <YearPickerHeading />
      <YearPickerNext />
    </YearPickerHeader>
    <YearPickerGrid>
      <YearPickerGridBody>
        <YearPickerGridRow>
          <YearPickerCell>
            <YearPickerCellTrigger />
          </YearPickerCell>
        </YearPickerGridRow>
      </YearPickerGridBody>
    </YearPickerGrid>
  </YearPickerRoot>
</template>

API Reference

Root

Contains all the parts of a year picker

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`calendarLabel`		`string` The accessible label for the year picker
`defaultPlaceholder`		`DateValue` The default placeholder date
`defaultValue`		`DateValue` The default value for the year picker
`dir`		`'ltr' \| 'rtl'` The reading direction of the calendar when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR.
`disabled`	`false`	`boolean` Whether the year picker is disabled
`initialFocus`	`false`	`boolean` If true, the year picker will focus the selected year, today, or the first year of the range on mount
`isYearDisabled`		`Matcher` A function that returns whether or not a year is disabled
`isYearUnavailable`		`Matcher` A function that returns whether or not a year is unavailable
`locale`		`string` The locale to use for formatting dates
`maxValue`		`DateValue` The maximum date that can be selected
`minValue`		`DateValue` The minimum date that can be selected
`modelValue`		`DateValue \| DateValue[]` The controlled checked state of the year picker
`multiple`	`false`	`boolean` Whether multiple years can be selected
`nextPage`		`((placeholder: DateValue) => DateValue)` A function that returns the next page of the year picker. Receives the current placeholder as an argument.
`placeholder`		`DateValue` The placeholder date, which is used to determine what year range to display when no date is selected
`preventDeselect`	`false`	`boolean` Whether or not to prevent the user from deselecting a date without selecting another date first
`prevPage`		`((placeholder: DateValue) => DateValue)` A function that returns the previous page of the year picker. Receives the current placeholder as an argument.
`readonly`	`false`	`boolean` Whether the year picker is readonly
`yearsPerPage`	`12`	`number` Number of years to display per page

Emit	Payload
`update:modelValue`	`[date: DateValue]` Event handler called whenever the model value changes
`update:placeholder`	`[date: DateValue]` Event handler called whenever the placeholder value changes

Slots (default)	Payload
`date`	`DateValue` The current date of the placeholder
`grid`	`Grid<DateValue>` The grid of years
`locale`	`string` The year picker locale
`modelValue`	`DateValue \| DateValue[] \| undefined` The current selected value

Methods	Type
`isYearDisabled`	`Matcher` A function that returns whether or not a year is disabled
`isYearUnavailable`	`Matcher` A function that returns whether or not a year is unavailable

Data Attribute	Value
`[data-readonly]`	Present when readonly
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid

Contains the navigation buttons and the heading segments.

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Prev Button

Calendar navigation button. It navigates the calendar one page (default: 12 years) in the past.

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`prevPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the prev page. Overwrites the `prevPage` function set on the `YearPickerRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Data Attribute	Value
`[data-disabled]`	Present when disabled

Next Button

Calendar navigation button. It navigates the calendar one page (default: 12 years) in the future.

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`nextPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the next page. Overwrites the `nextPage` function set on the `YearPickerRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Data Attribute	Value
`[data-disabled]`	Present when disabled

Heading

Heading for displaying the current year range (e.g., "2020 - 2031").

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Slots (default)	Payload
`headingValue`	`string` Current year range heading

Data Attribute	Value
`[data-disabled]`	Present when disabled

Grid

Container for wrapping the year picker grid.

Prop	Default	Type
`as`	`'table'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-readonly]`	Present when readonly
`[data-disabled]`	Present when disabled

Grid Body

Container for wrapping the grid body.

Prop	Default	Type
`as`	`'tbody'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Grid Row

Container for wrapping the grid row.

Prop	Default	Type
`as`	`'tr'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Cell

Container for wrapping the year picker cells.

Prop	Default	Type
`as`	`'td'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`date*`		`DateValue` The date value for the cell

Data Attribute	Value
`[data-disabled]`	Present when disabled

Cell Trigger

Interactable container for displaying the cell years. Clicking it selects the year.

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`year*`		`DateValue` The date value provided to the cell trigger

Slots (default)	Payload
`yearValue`	`string` Current year value
`disabled`	`boolean` Current disable state
`selected`	`boolean` Current selected state
`today`	`boolean` Current year is today state
`unavailable`	`boolean` Current unavailable state

Data Attribute	Value
`[data-selected]`	Present when selected
`[data-value]`	The ISO string value of the date.
`[data-disabled]`	Present when disabled
`[data-unavailable]`	Present when unavailable
`[data-today]`	Present when the year is the current year
`[data-focused]`	Present when focused

Accessibility

Keyboard Interactions

Key	Description
`Tab`	When focus moves onto the year picker, focuses the first navigation button.
`Space`	When the focus is on either `YearPickerNext` or `YearPickerPrev`, it navigates the calendar. Otherwise, it selects the year.
`Enter`	When the focus is on either `YearPickerNext` or `YearPickerPrev`, it navigates the calendar. Otherwise, it selects the year.
`ArrowLeftArrowRightArrowUpArrowDown`	When the focus is on `YearPickerCellTrigger`, it navigates the years, changing the page if necessary.
`PageUp`	When the focus is on `YearPickerCellTrigger`, it navigates to the previous page of years.
`PageDown`	When the focus is on `YearPickerCellTrigger`, it navigates to the next page of years.

Year Picker ​

Features ​

Preface ​

Installation ​

Anatomy ​

API Reference ​

Root ​

Header ​

Prev Button ​

Next Button ​

Heading ​

Grid ​

Grid Body ​

Grid Row ​

Cell ​

Cell Trigger ​

Accessibility ​

Keyboard Interactions ​