---
title: "YearPicker"
description: "Presents a calendar view tailored for selecting years."
canonical_url: "https://vinicunca.dev/akar/components/year-picker"
---
# YearPicker

> Presents a calendar view tailored for selecting years.

## Year Picker

`````vue [index.vue]
<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>
```

```css [styles.css]
@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](https://react-spectrum.adobe.com/internationalized/date/index.html) 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.

```bash [pnpm]
pnpm add @internationalized/date
```

```bash [yarn]
yarn add @internationalized/date
```

```bash [npm]
npm install @internationalized/date
```

```bash [bun]
bun add @internationalized/date
```

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<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

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/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[] \| null` | The controlled selected year value of the year picker. Can be bound as `v-model`. |
| `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 |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `date: DateValue \| DateValue[]` | Event handler called whenever the model value changes |
| `update:placeholder` | `date: DateValue` | Event handler called whenever the placeholder value changes |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `date` | `DateValue` | The current date of the placeholder |
| `grid` | `Grid<DateValue>` | The grid of years |
| `locale` | `string` | The year picker locale |
| `modelValue` | `DateValue \| DateValue[]` | The current selected value |

[YearPickerRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerRoot.vue)

| 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.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[YearPickerHeader.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerHeader.vue)

### Prev Button

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

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/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**

| Slot | Payload | Description |
| --- | --- | --- |
| `disabled` | `boolean` | Current disable state |

[YearPickerPrev.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerPrev.vue)

| 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.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/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**

| Slot | Payload | Description |
| --- | --- | --- |
| `disabled` | `boolean` | Current disable state |

[YearPickerNext.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerNext.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |

### Heading

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

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `headingValue` | `string` | Current year range heading |

[YearPickerHeading.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerHeading.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |

### Grid

Container for wrapping the year picker grid.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[YearPickerGrid.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerGrid.vue)

| Data attribute | Value |
| --- | --- |
| `[data-readonly]` | Present when readonly |
| `[data-disabled]` | Present when disabled |

### Grid Body

Container for wrapping the grid body.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[YearPickerGridBody.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerGridBody.vue)

### Grid Row

Container for wrapping the grid row.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[YearPickerGridRow.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerGridRow.vue)

### Cell

Container for wrapping the year picker cells.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `date*` |  | `DateValue` | The date value for the cell |

[YearPickerCell.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerCell.vue)

| Data attribute | Value |
| --- | --- |
| `[data-disabled]` | Present when disabled |

### Cell Trigger

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

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `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.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `year*` |  | `DateValue` | The date value provided to the cell trigger |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `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 |

[YearPickerCellTrigger.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker/YearPickerCellTrigger.vue)

| 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 |
| --- | --- |
| <kbd>Tab</kbd> | When focus moves onto the year picker, focuses the first navigation button. |
| <kbd>Space</kbd> |  When the focus is on either `YearPickerNext` or `YearPickerPrev`, it navigates the calendar. Otherwise, it selects the year.  |
| <kbd>Enter</kbd> |  When the focus is on either `YearPickerNext` or `YearPickerPrev`, it navigates the calendar. Otherwise, it selects the year.  |
| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> / <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd> | When the focus is on `YearPickerCellTrigger`, it navigates the years, changing the page if necessary. |
| <kbd>PageUp</kbd> | When the focus is on `YearPickerCellTrigger`, it navigates to the previous page of years. |
| <kbd>PageDown</kbd> | When the focus is on `YearPickerCellTrigger`, it navigates to the next page of years. |

---

- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/YearPicker)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.