Month Picker
Accessible month grid with locale labels, paging, constraints, and single or multiple selection.
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
Selected: 2026-08-01
Examples
Multiple months
Set multiple to use an array model. Activating an already selected month removes it unless preventDeselect is enabled.
<template>
<Avatar
src="/avatar.jpg"
alt="Jane Doe"
text="JD"
:delay-ms="300"
/>
</template>
Constraints and unavailable months
Use minValue and maxValue for hard boundaries. Use isMonthDisabled for application rules and isMonthUnavailable for valid but unselectable periods.
<Button
:ui="{
root: 'rounded-md bg-black px-3 py-2 text-white',
spinner: 'size-4 animate-spin',
}"
>
Save
</Button>
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.
<script setup lang="ts">
import { ref } from 'vue'
import { Tabs } from 'akaza-ui'
const active = ref('account')
const items = [
{ value: 'account', label: 'Account' },
{ value: 'security', label: 'Security' },
]
</script>
<template>
<Tabs v-model="active" :items="items" aria-label="Settings">
<template #panel-account>Account settings…</template>
<template #panel-security>Security settings…</template>
</Tabs>
</template>
Custom month content
The month slot changes visible button content without replacing keyboard or ARIA behavior.
<Accordion
:items="items"
@value-change="(value, details) => {
if (details.reason === 'trigger') console.log('opened:', value)
}"
/>
Cancel changes
Selection and page updates emit cancelable details before mutating their models.
<script setup lang="ts">
import { createToastManager, provideToastManager, Toast } from "akaza-ui";
const manager = provideToastManager(createToastManager({ duration: 6000 }));
</script>
<template>
<RouterView />
<Toast :manager="manager" />
</template>
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
| Model | Type | Default | Description |
|---|---|---|---|
v-model | CalendarDateValue | CalendarDateValue[] | undefined | undefined | Selected month or selected months when multiple is enabled. Values are normalized to day 1. |
v-model:placeholder | CalendarDateValue | selected month or today | Year displayed by the grid. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
locale | string | "en-US" | Locale used for month and year labels. |
dir | "ltr" | "rtl" | "ltr" | Reading direction and horizontal arrow behavior. |
calendarLabel | string | "Month picker" | Accessible root label. |
columns | number | 3 | Number of month columns. |
multiple | boolean | false | Enables independent multiple selection. |
preventDeselect | boolean | false | Prevents removing an already selected month. |
disabled | boolean | false | Disables paging and selection. |
readOnly | boolean | false | Allows navigation but blocks selection. |
initialFocus | boolean | false | Focuses the selected month, current month, or first visible month on mount. |
minValue | CalendarDateValue | — | Earliest selectable month and page boundary. |
maxValue | CalendarDateValue | — | Latest selectable month and page boundary. |
isMonthDisabled | (date) => boolean | — | Marks a month disabled by application rules. |
isMonthUnavailable | (date) => boolean | — | Marks a month unavailable. |
nextPage | (placeholder) => CalendarDateValue | add one year | Custom next-page calculation. |
prevPage | (placeholder) => CalendarDateValue | subtract one year | Custom previous-page calculation. |
ui | MonthPickerUi | — | Classes for generated parts. |
Emits
| Event | Payload | Description |
|---|---|---|
update:modelValue | value | Fires after accepted selection changes. |
update:placeholder | date | Fires after accepted page changes. |
value-change | (value, details) | Fires before selection. details.cancel() prevents update. |
placeholder-change | (date, details) | Fires before paging. details.cancel() prevents update. |
Slots
| Slot | Props | Description |
|---|---|---|
previous | disabled | Previous control content. |
heading | label, items | Current year heading. |
next | disabled | Next control content. |
month | date, label, selected, today, disabled, unavailable, focused | Month button content and state. |
footer | value, placeholder | Optional content after grid. |
Methods
| Method | Description |
|---|---|
focusValue(date) | Moves roving focus to a month and pages when needed. |
selectValue(date, event?) | Requests month selection. |
nextPage(event?) | Requests next page. |
previousPage(event?) | Requests previous page. |
UI Options
| Key | Part |
|---|---|
root | Root group. |
header | Navigation header. |
previous | Previous-year button. |
heading | Live year heading. |
next | Next-year button. |
grid | ARIA month grid. |
gridRow | Grid row. |
cell | Grid cell. |
cellTrigger | Interactive month button. |
footer | Optional footer. |
Styling Hooks
| UI key | CSS class | Data attributes |
|---|---|---|
root | .akaza-month-picker | data-akaza-state, data-akaza-selection-mode, data-akaza-disabled, data-akaza-readonly, data-akaza-invalid |
header | .akaza-month-picker-header | — |
previous | .akaza-month-picker-previous | data-akaza-disabled |
heading | .akaza-month-picker-heading | — |
next | .akaza-month-picker-next | data-akaza-disabled |
grid | .akaza-month-picker-grid | — |
gridRow | .akaza-month-picker-grid-row | — |
cell | .akaza-month-picker-cell | selection and availability attributes listed below |
cellTrigger | .akaza-month-picker-cell-trigger | data-akaza-state, data-akaza-selected, data-akaza-today, data-akaza-disabled, data-akaza-unavailable |
footer | .akaza-month-picker-footer | — |
Keyboard
| Key | Behavior |
|---|---|
ArrowLeft / ArrowRight | Moves one month, reversed in RTL. |
ArrowUp / ArrowDown | Moves one visual row using columns. |
Home / End | Moves to first or last month in current row. |
PageUp / PageDown | Moves one year. |
Shift + PageUp / Shift + PageDown | Moves ten years. |
Enter / Space | Selects focused month. |
Native buttons provide pointer and touch activation. Focus never scrolls the document unexpectedly.