---
title: "MonthPicker"
description: "Presents a calendar view tailored for selecting months."
canonical_url: "https://vinicunca.dev/akar/components/month-picker"
---
# MonthPicker

> Presents a calendar view tailored for selecting months.

## Month Picker

`````vue [index.vue]
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'
import { MonthPickerCell, MonthPickerCellTrigger, MonthPickerGrid, MonthPickerGridBody, MonthPickerGridRow, MonthPickerHeader, MonthPickerHeading, MonthPickerNext, MonthPickerPrev, MonthPickerRoot } from 'akar'
import './styles.css'

const date = new CalendarDate(2024, 10, 1)
</script>

<template>
  <div class="akar-demo akar-demo-MonthPicker">
    <MonthPickerRoot
        v-slot="{ grid }"
        :default-value="date"
        class="MonthPicker"
      >
        <MonthPickerHeader class="MonthPickerHeader">
          <MonthPickerPrev class="MonthPickerNavButton">
            <PIcon
              name="i-lucide-chevron-left"
              class="Icon"
            />
          </MonthPickerPrev>
          <MonthPickerHeading class="MonthPickerHeading" />
          <MonthPickerNext class="MonthPickerNavButton">
            <PIcon
              name="i-lucide-chevron-right"
              class="Icon"
            />
          </MonthPickerNext>
        </MonthPickerHeader>
        <div class="MonthPickerWrapper">
          <MonthPickerGrid class="MonthPickerGrid">
            <MonthPickerGridBody class="MonthPickerGridWrapper">
              <MonthPickerGridRow
                v-for="(months, index) in grid.rows"
                :key="`month-${index}`"
                class="MonthPickerGridRow"
              >
                <MonthPickerCell
                  v-for="month in months"
                  :key="month.toString()"
                  :date="month"
                  class="MonthPickerCell"
                >
                  <MonthPickerCellTrigger
                    :month="month"
                    class="MonthPickerCellTrigger"
                  />
                </MonthPickerCell>
              </MonthPickerGridRow>
            </MonthPickerGridBody>
          </MonthPickerGrid>
        </div>
      </MonthPickerRoot>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';

@scope (.akar-demo-MonthPicker) {
.Icon {
  width: 1rem;
  height: 1rem;
}

.MonthPicker {
  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;
}

.MonthPickerHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.MonthPickerNavButton {
  display: inline-flex;
  justify-content: center;
  align-items: center;
  width: 2rem;
  height: 2rem;
  color: #000000;
  background-color: transparent;
  cursor: pointer;
  border-radius: 0.375rem;
}

.MonthPickerNavButton:hover {
  background-color: #fafaf9;
}

.MonthPickerNavButton:focus {
  box-shadow: 0 0 0 2px #000000;
}

.MonthPickerHeading {
  font-size: 0.875rem;
  font-weight: 500;
  color: #000000;
}

.MonthPickerWrapper {
  padding-top: 1rem;
}

.MonthPickerGrid {
  width: 100%;
  user-select: none;
}

.MonthPickerGridWrapper {
  display: grid;
  gap: 0.25rem 0;
}

.MonthPickerGridRow {
  display: grid;
  grid-template-columns: repeat(4, minmax(0, 1fr));
  gap: 0.25rem;
}

.MonthPickerCell {
  position: relative;
  text-align: center;
}

.MonthPickerCellTrigger {
  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;
}

.MonthPickerCellTrigger:hover {
  background-color: var(--grass-5);
}

.MonthPickerCellTrigger:focus {
  box-shadow: 0 0 0 2px #000000;
}

.MonthPickerCellTrigger[data-disabled] {
  color: rgba(0, 0, 0, 0.3);
  pointer-events: none;
}

.MonthPickerCellTrigger[data-selected] {
  background-color: var(--grass-10);
  color: #ffffff;
  font-weight: 500;
}

.MonthPickerCellTrigger[data-unavailable] {
  color: rgba(0, 0, 0, 0.3);
  text-decoration: line-through;
  pointer-events: none;
}

.MonthPickerCellTrigger::before {
  content: '';
  position: absolute;
  top: 0.25rem;
  width: 0.25rem;
  height: 0.25rem;
  border-radius: 9999px;
  display: none;
}

.MonthPickerCellTrigger[data-today]::before {
  display: block;
  background-color: var(--grass-9);
}

.MonthPickerCellTrigger[data-selected]::before {
  background-color: #ffffff;
}
}
```

## 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](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 {
  MonthPickerCell,
  MonthPickerCellTrigger,
  MonthPickerGrid,
  MonthPickerGridBody,
  MonthPickerGridRow,
  MonthPickerHeader,
  MonthPickerHeading,
  MonthPickerNext,
  MonthPickerPrev,
  MonthPickerRoot,
} from 'akar';
</script>

<template>
  <MonthPickerRoot>
    <MonthPickerHeader>
      <MonthPickerPrev />
      <MonthPickerHeading />
      <MonthPickerNext />
    </MonthPickerHeader>
    <MonthPickerGrid>
      <MonthPickerGridBody>
        <MonthPickerGridRow>
          <MonthPickerCell>
            <MonthPickerCellTrigger />
          </MonthPickerCell>
        </MonthPickerGridRow>
      </MonthPickerGridBody>
    </MonthPickerGrid>
  </MonthPickerRoot>
</template>
```

## API Reference

### Root

Contains all the parts of a month 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 month picker |
| `defaultPlaceholder` |  | `DateValue` | The default placeholder date |
| `defaultValue` |  | `DateValue` | The default value for the month 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 month picker is disabled |
| `initialFocus` | `false` | `boolean` | If true, the month picker will focus the selected month, today, or the first month of the year on mount |
| `isMonthDisabled` |  | `Matcher` | A function that returns whether or not a month is disabled |
| `isMonthUnavailable` |  | `Matcher` | A function that returns whether or not a month 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 month value of the month picker. Can be bound as `v-model`. |
| `multiple` | `false` | `boolean` | Whether multiple months can be selected |
| `nextPage` |  | `((placeholder: DateValue) => DateValue)` | A function that returns the next page of the month picker. Receives the current placeholder as an argument. |
| `placeholder` |  | `DateValue` | The placeholder date, which is used to determine what year 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 month picker. Receives the current placeholder as an argument. |
| `readonly` | `false` | `boolean` | Whether the month picker is readonly |

**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 months |
| `locale` | `string` | The month picker locale |
| `modelValue` | `DateValue \| DateValue[]` | The current selected value |

[MonthPickerRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/MonthPicker/MonthPickerRoot.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. |

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

### Prev Button

Calendar navigation button. It navigates the calendar one year 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 `MonthPickerRoot`. |

**Slots**

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

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

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

### Next Button

Calendar navigation button. It navigates the calendar one year 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 `MonthPickerRoot`. |

**Slots**

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

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

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

### Heading

Heading for displaying the current 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. |

**Slots**

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

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

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

### Grid

Container for wrapping the month 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. |

[MonthPickerGrid.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/MonthPicker/MonthPickerGrid.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. |

[MonthPickerGridBody.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/MonthPicker/MonthPickerGridBody.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. |

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

### Cell

Container for wrapping the month 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 |

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

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

### Cell Trigger

Interactable container for displaying the cell months. Clicking it selects the month.

**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. |
| `month*` |  | `DateValue` | The date value provided to the cell trigger |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `monthValue` | `string` | Current month value (short name) |
| `disabled` | `boolean` | Current disable state |
| `selected` | `boolean` | Current selected state |
| `today` | `boolean` | Current month/year is today state |
| `unavailable` | `boolean` | Current unavailable state |

[MonthPickerCellTrigger.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/MonthPicker/MonthPickerCellTrigger.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 month is the current month |
| `[data-focused]` | Present when focused |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| <kbd>Tab</kbd> | When focus moves onto the month picker, focuses the first navigation button. |
| <kbd>Space</kbd> |  When the focus is on either `MonthPickerNext` or `MonthPickerPrev`, it navigates the calendar. Otherwise, it selects the month.  |
| <kbd>Enter</kbd> |  When the focus is on either `MonthPickerNext` or `MonthPickerPrev`, it navigates the calendar. Otherwise, it selects the month.  |
| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> / <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd> | When the focus is on `MonthPickerCellTrigger`, it navigates the months, changing the year if necessary. |
| <kbd>PageUp</kbd> | When the focus is on `MonthPickerCellTrigger`, it navigates to the same month in the previous year. |
| <kbd>PageDown</kbd> | When the focus is on `MonthPickerCellTrigger`, it navigates to the same month in the next year. |

---

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


## Sitemap

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