Skip to content

Month Range Picker

Select a range of months.

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 MonthRangePicker.vue and index.ts into app/components/ui/month-range-picker/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Models

ModelTypeDefaultDescription
v-modelCalendarDateRange{}Optional normalized start and end months.
v-model:placeholderCalendarDateValueselected start or todayYear displayed by grid.

See Range selection for preview fills and primary-colored endpoints.

Props

PropTypeDefaultDescription
rangeColor"secondary" | "accent""secondary"Preview and committed middle fill; endpoints use primary.
localestring"en-US"Locale used for labels.
dir"ltr" | "rtl""ltr"Reading direction and horizontal arrows.
calendarLabelstring"Month range picker"Accessible root label.
columnsnumber3Number of month columns.
allowNonContiguousRangesbooleanfalseAllows blocked interior months.
maximumMonthsnumber—Maximum inclusive range length.
fixedDate"start" | "end"—Keeps one endpoint fixed.
disabledbooleanfalseDisables paging and selection.
readOnlybooleanfalseAllows navigation but blocks selection.
initialFocusbooleanfalseFocuses selected/current month on mount.
minValueCalendarDateValue—Earliest selectable month.
maxValueCalendarDateValue—Latest selectable month.
isMonthDisabled(date) => boolean—Marks months disabled.
isMonthUnavailable(date) => boolean—Marks months unavailable.
nextPage(placeholder) => CalendarDateValueadd one yearCustom next page.
prevPage(placeholder) => CalendarDateValuesubtract one yearCustom previous page.
uiMonthRangePickerUi—Classes for generated parts.

Slots

SlotPropsDescription
previousdisabledPrevious control content.
headinglabel, itemsYear heading.
nextdisabledNext control content.
monthdate, label, selected, rangeStart, rangeEnd, inRange, highlighted, disabled, unavailable, focusedMonth content and range state.
footervalue, placeholderOptional footer.

Events

EventPayloadDescription
update:modelValueCalendarDateRangeFires after accepted range changes.
update:placeholderCalendarDateValueFires after accepted page changes.
value-change(range, details)Cancelable range change.
placeholder-change(date, details)Cancelable page change.

Keyboard

KeyBehavior
Arrow keysMove one month horizontally or one columns row vertically. Horizontal movement reverses in RTL.
Home / EndMoves to row boundary.
PageUp / PageDownMoves one year.
Shift + PageUp / Shift + PageDownMoves ten years.
Enter / SpaceSets range start or completes range end.

Pointer hover previews a pending range; touch activation selects endpoints without relying on hover.