Skip to content

Year Range Picker

Select a range of years.

Demos

Size
2026 – 2037

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

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Models

ModelTypeDefaultDescription
v-modelCalendarDateRange{}Optional start and end years normalized to January 1.
v-model:placeholderCalendarDateValueselected start or todayFirst visible year.

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.
calendarLabelstring"Year range picker"Accessible root label.
columnsnumber3Visual grid columns.
yearsPerPagenumber12Visible years and paging distance.
allowNonContiguousRangesbooleanfalseAllows blocked interior years.
maximumYearsnumber—Maximum inclusive range length.
fixedDate"start" | "end"—Keeps one endpoint fixed.
disabledbooleanfalseDisables paging and selection.
readOnlybooleanfalseAllows navigation but blocks selection.
initialFocusbooleanfalseFocuses selected/current year on mount.
minValue / maxValueCalendarDateValue—Selection and paging boundaries.
isYearDisabled(date) => boolean—Marks years disabled.
isYearUnavailable(date) => boolean—Marks years unavailable.
nextPage / prevPage(placeholder) => CalendarDateValuepage arithmeticCustom page calculations.
uiYearRangePickerUi—Classes for generated parts.

Slots

SlotPropsDescription
previousdisabledPrevious control content.
headinglabel, itemsVisible year-range heading.
nextdisabledNext control content.
yeardate, label, selected, rangeStart, rangeEnd, inRange, highlighted, disabled, unavailable, focusedYear content and range state.
footervalue, placeholderOptional content after grid.

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 by one year or one visual row. Horizontal movement reverses in RTL.
Home / EndMoves to row boundary.
PageUp / PageDownMoves one page.
Shift + PageUp / Shift + PageDownMoves ten pages.
Enter / SpaceSets range start or completes range end.

Pointer hover and keyboard focus preview a pending range. Touch input selects each endpoint.