Month Picker

MonthPicker displays one year at a time as a month grid. It supports roving focus, year paging, locale labels, constraints, and single or multiple selection.

Use Month Picker for values that do not need a day. Slots and ui style its generated parts.

Anatomy

• #previous: Previous-year control content with disabled state.
• #heading: Current year label and visible month items.
• #next: Next-year control content with disabled state.
• #month: Month button content with date, label, selected, today, focused, disabled, and unavailable state.
• #footer: Optional content after the grid with current value and placeholder.

Month Picker generates the root, header, navigation buttons, live heading, ARIA grid, rows, cells, and month buttons.

Usage

<script setup lang="ts">
import type { CalendarDateValue, MonthPickerModelValue } from "akaza-ui";
import { CalendarDate } from "@internationalized/date";
import { shallowRef } from "vue";
import { MonthPicker } from "akaza-ui";

const value = shallowRef<MonthPickerModelValue>(new CalendarDate(2026, 8, 1));
const page = shallowRef<CalendarDateValue>(new CalendarDate(2026, 1, 1));
</script>

<template>
  <MonthPicker v-model="value" v-model:placeholder="page" />
</template>

Examples

Multiple months

Set multiple to use an array model. Activating an already selected month removes it unless preventDeselect is enabled.

<MonthPicker v-model="months" multiple />

Constraints and unavailable months

Use minValue and maxValue for hard boundaries. Use isMonthDisabled for application rules and isMonthUnavailable for valid but unselectable periods.

<MonthPicker
  v-model="month"
  :min-value="new CalendarDate(2026, 3, 1)"
  :max-value="new CalendarDate(2026, 10, 1)"
  :is-month-unavailable="date => date.month === 7"
/>

Blocked months remain keyboard discoverable through aria-disabled, but activation does not update the model.

Controlled paging

Bind v-model:placeholder when application state must own the displayed year. nextPage and prevPage can replace default one-year arithmetic.

<MonthPicker
  v-model="month"
  v-model:placeholder="visibleYear"
  :next-page="date => date.add({ years: 2 })"
  :prev-page="date => date.subtract({ years: 2 })"
/>

Custom month content

The month slot changes visible button content without replacing keyboard or ARIA behavior.

<MonthPicker>
  <template #month="{ label, selected, today }">
    <span :class="{ 'font-bold': selected, underline: today }">{{ label }}</span>
  </template>
</MonthPicker>

Cancel changes

Selection and page updates emit cancelable details before mutating their models.

<MonthPicker
  v-model="month"
  @value-change="(_value, details) => locked && details.cancel()"
/>

Calendar-aware pages

Previous/next move by calendar year, not a fixed twelve months. This includes calendars with leap months, such as Hebrew. Visible month/year labels use the value's calendar and the requested locale.

API Reference

Models

Props

Emits

Slots

Methods

UI Options

Styling Hooks

Keyboard

Native buttons provide pointer and touch activation. Focus never scrolls the document unexpectedly.