Year Picker
Alpha2020 | 2021 | 2022 | 2023 |
2024 | 2025 | 2026 | 2027 |
2028 | 2029 | 2030 | 2031 |
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date';
import { YearPickerCell, YearPickerCellTrigger, YearPickerGrid, YearPickerGridBody, YearPickerGridRow, YearPickerHeader, YearPickerHeading, YearPickerNext, YearPickerPrev, YearPickerRoot } from 'akar';
import './styles.css';
const date = new CalendarDate(2024, 1, 1);
</script>
<template>
<div class="akar-demo akar-demo-YearPicker">
<YearPickerRoot
v-slot="{ grid }"
:default-value="date"
class="YearPicker"
>
<YearPickerHeader class="YearPickerHeader">
<YearPickerPrev class="YearPickerNavButton">
<PIcon
name="i-lucide-chevron-left"
class="Icon"
/>
</YearPickerPrev>
<YearPickerHeading class="YearPickerHeading" />
<YearPickerNext class="YearPickerNavButton">
<PIcon
name="i-lucide-chevron-right"
class="Icon"
/>
</YearPickerNext>
</YearPickerHeader>
<div class="YearPickerWrapper">
<YearPickerGrid class="YearPickerGrid">
<YearPickerGridBody class="YearPickerGridWrapper">
<YearPickerGridRow
v-for="(years, index) in grid.rows"
:key="`year-${index}`"
class="YearPickerGridRow"
>
<YearPickerCell
v-for="year in years"
:key="year.toString()"
:date="year"
class="YearPickerCell"
>
<YearPickerCellTrigger
:year="year"
class="YearPickerCellTrigger"
/>
</YearPickerCell>
</YearPickerGridRow>
</YearPickerGridBody>
</YearPickerGrid>
</div>
</YearPickerRoot>
</div>
</template>@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';
@scope (.akar-demo-YearPicker) {
.Icon {
width: 1rem;
height: 1rem;
}
.YearPicker {
margin-top: 1.5rem;
border-radius: 0.75rem;
border: 1px solid #e5e5e5;
background-color: #ffffff;
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
padding: 1rem;
}
.YearPickerHeader {
display: flex;
justify-content: space-between;
align-items: center;
}
.YearPickerNavButton {
display: inline-flex;
justify-content: center;
align-items: center;
width: 2rem;
height: 2rem;
color: #000000;
background-color: transparent;
cursor: pointer;
border-radius: 0.375rem;
}
.YearPickerNavButton:hover {
background-color: #fafaf9;
}
.YearPickerNavButton:focus {
box-shadow: 0 0 0 2px #000000;
}
.YearPickerHeading {
font-size: 0.875rem;
font-weight: 500;
color: #000000;
}
.YearPickerWrapper {
padding-top: 1rem;
}
.YearPickerGrid {
width: 100%;
user-select: none;
}
.YearPickerGridWrapper {
display: grid;
gap: 0.25rem 0;
}
.YearPickerGridRow {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 0.25rem;
}
.YearPickerCell {
position: relative;
text-align: center;
}
.YearPickerCellTrigger {
position: relative;
display: flex;
justify-content: center;
align-items: center;
width: 3rem;
height: 3rem;
border-radius: 0.5rem;
font-size: 0.875rem;
font-weight: 400;
color: #000000;
background-color: transparent;
outline: none;
cursor: pointer;
border: none;
}
.YearPickerCellTrigger:hover {
background-color: var(--grass-5);
}
.YearPickerCellTrigger:focus {
box-shadow: 0 0 0 2px #000000;
}
.YearPickerCellTrigger[data-disabled] {
color: rgba(0, 0, 0, 0.3);
pointer-events: none;
}
.YearPickerCellTrigger[data-selected] {
background-color: var(--grass-10);
color: #ffffff;
font-weight: 500;
}
.YearPickerCellTrigger[data-unavailable] {
color: rgba(0, 0, 0, 0.3);
text-decoration: line-through;
pointer-events: none;
}
.YearPickerCellTrigger::before {
content: '';
position: absolute;
top: 0.25rem;
width: 0.25rem;
height: 0.25rem;
border-radius: 9999px;
display: none;
}
.YearPickerCellTrigger[data-today]::before {
display: block;
background-color: var(--grass-9);
}
.YearPickerCellTrigger[data-selected]::before {
background-color: #ffffff;
}
}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.
pnpm add @internationalized/date
yarn add @internationalized/date
npm install @internationalized/date
bun add @internationalized/date
Install the component from your command line.
pnpm add akar
yarn add akar
npm install akar
bun add akar
Anatomy
Import all parts and piece them together.
<script setup>
import {
YearPickerCell,
YearPickerCellTrigger,
YearPickerGrid,
YearPickerGridBody,
YearPickerGridRow,
YearPickerHeader,
YearPickerHeading,
YearPickerNext,
YearPickerPrev,
YearPickerRoot,
} from 'akar';
</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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
calendarLabel | stringThe accessible label for the year picker | |
defaultPlaceholder | DateValueThe default placeholder date | |
defaultValue | DateValueThe default value for the year picker | |
dir | "ltr" | "rtl"The reading direction of the calendar when applicable. If omitted, inherits globally from | |
disabled | false | booleanWhether the year picker is disabled |
initialFocus | false | booleanIf true, the year picker will focus the selected year, today, or the first year of the range on mount |
isYearDisabled | MatcherA function that returns whether or not a year is disabled | |
isYearUnavailable | MatcherA function that returns whether or not a year is unavailable | |
locale | stringThe locale to use for formatting dates | |
maxValue | DateValueThe maximum date that can be selected | |
minValue | DateValueThe minimum date that can be selected | |
modelValue | DateValue | DateValue[] | nullThe controlled selected year value of the year picker. Can be bound as | |
multiple | false | booleanWhether 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 | DateValueThe placeholder date, which is used to determine what year range to display when no date is selected | |
preventDeselect | false | booleanWhether 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 | booleanWhether the year picker is readonly |
yearsPerPage | 12 | numberNumber of years to display per page |
| Event | Payload |
|---|---|
update:modelValue | date: DateValue | DateValue[]Event handler called whenever the model value changes |
update:placeholder | date: DateValueEvent handler called whenever the placeholder value changes |
| Slot (default) | Payload |
|---|---|
date | DateValueThe current date of the placeholder |
grid | Grid<DateValue>The grid of years |
locale | stringThe year picker locale |
modelValue | DateValue | DateValue[]The current selected value |
| Data attribute | Value |
|---|---|
[data-readonly] | Present when readonly |
[data-disabled] | Present when disabled |
[data-invalid] | Present when invalid |
Header
Contains the navigation buttons and the heading segments.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 |
| Slot (default) | Payload |
|---|---|
disabled | booleanCurrent 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 |
| Slot (default) | Payload |
|---|---|
disabled | booleanCurrent 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
| Slot (default) | Payload |
|---|---|
headingValue | stringCurrent 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
date* | DateValueThe 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 | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
year* | DateValueThe date value provided to the cell trigger |
| Slot (default) | Payload |
|---|---|
yearValue | stringCurrent year value |
disabled | booleanCurrent disable state |
selected | booleanCurrent selected state |
today | booleanCurrent year is today state |
unavailable | booleanCurrent 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. |
| ArrowLeft/ArrowRight/ArrowUp/ArrowDown | 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. |