Year Range Picker

Alpha

Presents a calendar view tailored for selecting year ranges.

View code

Year Picker, 2020 - 2031

2020 - 2031

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

Features

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

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 {
  YearRangePickerCell,
  YearRangePickerCellTrigger,
  YearRangePickerGrid,
  YearRangePickerGridBody,
  YearRangePickerGridRow,
  YearRangePickerHeader,
  YearRangePickerHeading,
  YearRangePickerNext,
  YearRangePickerPrev,
  YearRangePickerRoot,
} from 'reka-ui'
</script>

<template>
  <YearRangePickerRoot>
    <YearRangePickerHeader>
      <YearRangePickerPrev />
      <YearRangePickerHeading />
      <YearRangePickerNext />
    </YearRangePickerHeader>
    <YearRangePickerGrid>
      <YearRangePickerGridBody>
        <YearRangePickerGridRow>
          <YearRangePickerCell>
            <YearRangePickerCellTrigger />
          </YearRangePickerCell>
        </YearRangePickerGridRow>
      </YearRangePickerGridBody>
    </YearRangePickerGrid>
  </YearRangePickerRoot>
</template>

API Reference

Root

Contains all the parts of a year range picker

Prop	Default	Type
`allowNonContiguousRanges`	`false`	`boolean` When combined with `isYearUnavailable`, determines whether non-contiguous ranges may be selected.
`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 calendar
`defaultPlaceholder`		`DateValue` The default placeholder date
`defaultValue`	`{ start: undefined, end: undefined }`	`DateRange` The default value for the calendar
`dir`		`'ltr' \| 'rtl'` The reading direction of the calendar when applicable.
`disabled`	`false`	`boolean` Whether or not the calendar is disabled
`fixedDate`		`'start' \| 'end'` Which part of the range should be fixed
`initialFocus`	`false`	`boolean` If true, the calendar will focus the selected year 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
`maximumYears`		`number` The maximum number of years that can be selected in a range
`maxValue`		`DateValue` The maximum date that can be selected
`minValue`		`DateValue` The minimum date that can be selected
`modelValue`		`DateRange \| null` The controlled checked state of the calendar. Can be bound as `v-model`.
`nextPage`		`((placeholder: DateValue) => DateValue)` A function that returns the next page of the calendar.
`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 calendar.
`readonly`	`false`	`boolean` Whether or not the calendar is readonly
`yearsPerPage`	`12`	`number` Number of years to display per page

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

Slots (default)	Payload
`date`	`DateValue` The current date of the placeholder
`grid`	`Grid<DateValue>` The grid of years
`locale`	`string` The calendar locale
`modelValue`	`DateRange` The current date range

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 (12 years by default) 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 Root.

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 (12 years by default) 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 Root.

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

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

Heading

Heading for displaying the current year range.

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 range 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 range 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's year state
`unavailable`	`boolean` Current unavailable state
`highlighted`	`boolean` Current highlighted state
`highlightedStart`	`boolean` Current highlighted start state
`highlightedEnd`	`boolean` Current highlighted end state
`selectionStart`	`boolean` Current selection start state
`selectionEnd`	`boolean` Current selection end 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-selection-start]`	Present when the year is the start of the selection.
`[data-selection-end]`	Present when the year is the end of the selection.
`[data-highlighted]`	Present when the year is highlighted by the user as they select a range.
`[data-highlighted-start]`	Present when the year is the start of the range that is highlighted by the user.
`[data-highlighted-end]`	Present when the year is the end of the range that is highlighted by the user.
`[data-focused]`	Present when focused

Accessibility

Keyboard Interactions

Key	Description
`Tab`	When focus moves onto the year range picker, focuses the first navigation button.
`Space`	When the focus is on either `YearRangePickerNext` or `YearRangePickerPrev`, it navigates the calendar. Otherwise, it selects the year.
`Enter`	When the focus is on either `YearRangePickerNext` or `YearRangePickerPrev`, it navigates the calendar. Otherwise, it selects the year.
`ArrowLeftArrowRightArrowUpArrowDown`	When the focus is on `YearRangePickerCellTrigger`, it navigates the years, changing the page if necessary.
`PageUp`	When the focus is on `YearRangePickerCellTrigger`, it navigates to the previous page of years.
`PageDown`	When the focus is on `YearRangePickerCellTrigger`, it navigates to the next page of years.
`Escape`	Cancels the current range selection and restores the previous valid range.

Year Range 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 ​