Skip to content

Month Picker

Select one or more months from a grid.

Demos

Size
2026

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Installation

Complete the shared installation. Copy MonthPicker.vue and index.ts into app/components/ui/month-picker/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Models

ModelTypeDefaultDescription
v-modelCalendarDateValue | CalendarDateValue[] | undefinedundefinedSelected month or selected months when multiple is enabled. Values are normalized to day 1.
v-model:placeholderCalendarDateValueselected month or todayYear displayed by the grid.

Props

PropTypeDefaultDescription
localestring"en-US"Locale used for month and year labels.
dir"ltr" | "rtl""ltr"Reading direction and horizontal arrow behavior.
calendarLabelstring"Month picker"Accessible root label.
columnsnumber3Number of month columns.
multiplebooleanfalseEnables independent multiple selection.
preventDeselectbooleanfalsePrevents removing an already selected month.
disabledbooleanfalseDisables paging and selection.
readOnlybooleanfalseAllows navigation but blocks selection.
initialFocusbooleanfalseFocuses the selected month, current month, or first visible month on mount.
minValueCalendarDateValue—Earliest selectable month and page boundary.
maxValueCalendarDateValue—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) => CalendarDateValueadd one yearCustom next-page calculation.
prevPage(placeholder) => CalendarDateValuesubtract one yearCustom previous-page calculation.
uiMonthPickerUi—Classes for generated parts.

Slots

SlotPropsDescription
previousdisabledPrevious control content.
headinglabel, itemsCurrent year heading.
nextdisabledNext control content.
monthdate, label, selected, today, disabled, unavailable, focusedMonth button content and state.
footervalue, placeholderOptional content after grid.

Events

EventPayloadDescription
update:modelValuevalueFires after accepted selection changes.
update:placeholderdateFires 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.

Keyboard

KeyBehavior
ArrowLeft / ArrowRightMoves one month, reversed in RTL.
ArrowUp / ArrowDownMoves one visual row using columns.
Home / EndMoves to first or last month in current row.
PageUp / PageDownMoves one year.
Shift + PageUp / Shift + PageDownMoves ten years.
Enter / SpaceSelects focused month.

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