Range Calendar
newFrom here to there, in two clicks. A calendar for the start and the end of something.
Open Props in the corner of the example to try color, size and disabled.
Installation
It installs Calendar too, for the shared styles.
Usage
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'
import type { DateRange } from 'reka-ui'
import { RangeCalendar } from '@/components/ui/range-calendar'
const stay = shallowRef<DateRange | null>({
start: new CalendarDate(2026, 10, 6),
end: new CalendarDate(2026, 10, 12),
})
</script>
<template>
<RangeCalendar v-model="stay" />
</template>
The first click picks the start, the second the end. Pick them in either order; the range comes back sorted. The ends are filled, the days between sit on a soft band, and while you choose the end a preview follows the pointer or the arrow keys.
v-model is { start, end } of @internationalized/date values. While the end is being picked it's { start, end: undefined }, so validate the whole range, or listen to update:valid-model-value, which fires only once both ends are there. Escape in the middle of a pick brings back the last complete range.
The demo above shows two months, with :number-of-months="2". They sit side by side from sm and stack below it, and with paged-navigation the arrows move by two. The days from the neighbouring months are hidden, band and all, since the other grid draws them again.
Everything else, from sizes and colours to locales, week numbers, slots and the Field wiring, works as on Calendar.
Examples
Maximum days
maximum-days caps the length: once a start is picked, the days beyond reach are disabled. A range can't cross unavailable days unless allow-non-contiguous-ranges is on.
Book up to 7 days.
Presets
Set v-model from outside, and move v-model:placeholder with it so the range is on screen.
Date picker
A Popover that closes on update:valid-model-value, so the first click doesn't close it. Escape mid-pick restores the last range and closes the popover in the same press.
Form
Check-in and check-out kept as ISO strings by Formisch. The schema wants both, and a check-out after the check-in. Pick one day, then the same day again.
Known limits
update:model-valuefires with half a range while the end is being picked (reka-ui#2396). Act onupdate:valid-model-valuewhen only finished ranges matter.- Escape inside a popover both restores the range and closes the popover (reka-ui#1536).
- The preview reuses the band's
--tone-soft; there's no separate token for it yet. - Calendar's known limits apply here too, except the one about
multiple.
API Reference
Every part accepts class, merged over its base classes.
RangeCalendar
| Prop | Default | Type and description |
|---|---|---|
| defaultPlaceholder | — | DateValueThe month to open on when |
| defaultValue | — | DateRangeThe starting selection when |
| modelValue | undefined | DateRange | nullThe range, bound with |
| placeholder | — | DateValueA date in the month on screen, bound with |
| allowNonContiguousRanges | — | booleanLets a range run across unavailable days. |
| pagedNavigation | — | booleanMakes Previous and Next move by |
| preventDeselect | — | booleanKeeps a click on the range's only day from clearing it. |
| maximumDays | — | numberThe longest range, in days. Once a start is picked, days beyond it are disabled. |
| weekStartsOn | — | WeekStartsOnThe first day of the week, from |
| weekdayFormat | — | WeekDayFormatHow the weekday headers are written: |
| calendarLabel | — | stringReplaces Reka's English "Event Date" in the root's accessible name. Inside a field, the field label is used instead. |
| fixedWeeks | true | booleanAlways draws six weeks, so the height doesn't change from month to month. |
| maxValue | — | DateValueThe latest date that can be picked. Later days are disabled, and Next stops at its month. |
| minValue | — | DateValueThe earliest date that can be picked. Earlier days are disabled, and Previous stops at its month. |
| locale | — | stringThe locale for month names, weekdays, digits and the week start. Defaults to the one Reka UI's |
| numberOfMonths | — | numberHow many months to show side by side. Below |
| disabled | — | booleanDisables every day and both arrows. Also set by a disabled field. |
| readonly | — | booleanKeeps the days focusable but not selectable. |
| initialFocus | — | booleanFocuses the selected day, today or the first focusable day on mount, skipping the hidden copies of other months' days. Useful in a popover. |
| isDateDisabled | — | MatcherReturns |
| isDateUnavailable | — | MatcherReturns |
| isDateHighlightable | — | MatcherReturns |
| dir | — | DirectionThe reading direction, which also mirrors the arrow keys. Defaults to the one Reka UI's |
| nextPage | — | ((placeholder: DateValue) => DateValue)Returns the placeholder Next moves to, for custom paging. |
| prevPage | — | ((placeholder: DateValue) => DateValue)Returns the placeholder Previous moves to, for custom paging. |
| disableDaysOutsideCurrentView | — | booleanDisables the days from the neighbouring months. They still show with one month; see |
| fixedDate | — | "start" | "end"Keeps the |
| asChild | — | booleanRender the single child instead of the root, merging the root's attributes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| size | "md" | CalendarSizeSets the day cells, arrows, gaps and text from |
| color | "primary" | CalendarColorThe tone of the selected day, the range's band and today's outline: |
| weekNumbers | — | booleanAdds a column of week numbers before each row, counted from the row's first day. Hidden from screen readers. |
| id | — | stringOverrides the |
| Event | Payload and description |
|---|---|
| update:modelValue | [date: DateRange]Fires when the range changes, including the partial |
| update:validModelValue | [date: DateRange]Fires once a range has both ends, in order. Listen to it to close a popover. |
| update:placeholder | [date: DateValue]Fires when the month on screen changes. |
| update:startValue | [date: DateValue | undefined]Fires when the start is picked, before there is an end. |
| Slot | Scope and description |
|---|---|
| default | { date: DateValue; grid: Grid<DateValue>[]; weekDays: string[]; weekStartsOn: WeekStartsOn; locale: string; fixedWeeks: boolean; modelValue: DateRange; }Replaces the built-in layout, with Reka's |
| heading | { headingValue: string; date: DateValue; setPlaceholder: (date: DateValue) => void; }The heading's content, with |
| week-day | { day: string; index: number; }A weekday header's content, with |
| day | { day: DateValue; dayValue: string; selected: boolean; today: boolean; disabled: boolean; unavailable: boolean; outsideView: boolean; outsideVisibleView: boolean; highlighted: boolean; highlightedStart: boolean; highlightedEnd: boolean; selectionStart: boolean; selectionEnd: boolean; }A day's content, with the Calendar fields plus |
| prev-icon | anyThe Previous arrow's icon, a chevron by default. |
| next-icon | anyThe Next arrow's icon, a chevron by default. |
RangeCalendarHeader
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a div, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The heading and the arrows. |
RangeCalendarHeading
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a div, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| id | — | stringOverrides the id the root gives the heading for its |
| Slot | Scope and description |
|---|---|
| default | { headingValue: string; date: DateValue; setPlaceholder: (date: DateValue) => void; }The heading's content, with |
RangeCalendarPrevButton
| Prop | Default | Type and description |
|---|---|---|
| prevPage | — | ((placeholder: DateValue) => DateValue)Returns the placeholder this button moves to, overriding the root's |
| asChild | — | booleanRender the single child instead of a button, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, a chevron that flips in right-to-left layouts. |
RangeCalendarNextButton
| Prop | Default | Type and description |
|---|---|---|
| nextPage | — | ((placeholder: DateValue) => DateValue)Returns the placeholder this button moves to, overriding the root's |
| asChild | — | booleanRender the single child instead of a button, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, a chevron that flips in right-to-left layouts. |
RangeCalendarGrid
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a table, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The head and body of one month. |
RangeCalendarGridHead
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a thead, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The weekday row. |
RangeCalendarGridBody
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a tbody, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The week rows. |
RangeCalendarGridRow
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a tr, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}A week's cells, or the weekday headers. |
RangeCalendarHeadCell
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a th, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The weekday's name. |
RangeCalendarCell
| Prop | Default | Type and description |
|---|---|---|
| date* | — | DateValueThe day this cell holds. |
| asChild | — | booleanRender the single child instead of a td, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The day's trigger. |
RangeCalendarCellTrigger
| Prop | Default | Type and description |
|---|---|---|
| day* | — | DateValueThe day this trigger picks. |
| month* | — | DateValueThe month of the grid it sits in, which tells days from the neighbouring months apart. |
| asChild | — | booleanRender the single child instead of a div, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { dayValue: string; disabled: boolean; selected: boolean; today: boolean; outsideView: boolean; outsideVisibleView: boolean; unavailable: boolean; highlighted: boolean; highlightedStart: boolean; highlightedEnd: boolean; selectionStart: boolean; selectionEnd: boolean; }The day's content, with the Calendar fields plus |
Props
- defaultPlaceholder
DateValueThe month to open on whenv-model:placeholderis not used. Defaults to the selection, or else today in the locale's calendar.- defaultValue
DateRangeThe starting selection whenv-modelis not used.- modelValue
undefined DateRange | nullThe range, bound withv-model:{ start, end }of@internationalized/datevalues, ornull. While the end is being picked,endisundefined.- placeholder
DateValueA date in the month on screen, bound withv-model:placeholder. Moving it pages the calendar without selecting anything.- allowNonContiguousRanges
booleanLets a range run across unavailable days.- pagedNavigation
booleanMakes Previous and Next move bynumberOfMonthsinstead of one month.- preventDeselect
booleanKeeps a click on the range's only day from clearing it.- maximumDays
numberThe longest range, in days. Once a start is picked, days beyond it are disabled.- weekStartsOn
WeekStartsOnThe first day of the week, from0(Sunday) to6. Leave it out to follow the locale.- weekdayFormat
WeekDayFormatHow the weekday headers are written:narrow(the default),shortorlong.- calendarLabel
stringReplaces Reka's English "Event Date" in the root's accessible name. Inside a field, the field label is used instead.- fixedWeeks
true booleanAlways draws six weeks, so the height doesn't change from month to month.- maxValue
DateValueThe latest date that can be picked. Later days are disabled, and Next stops at its month.- minValue
DateValueThe earliest date that can be picked. Earlier days are disabled, and Previous stops at its month.- locale
stringThe locale for month names, weekdays, digits and the week start. Defaults to the one Reka UI'sConfigProvidersets.- numberOfMonths
numberHow many months to show side by side. Belowsmthey stack. With more than one, the days outside each month are hidden.- disabled
booleanDisables every day and both arrows. Also set by a disabled field.- readonly
booleanKeeps the days focusable but not selectable.- initialFocus
booleanFocuses the selected day, today or the first focusable day on mount, skipping the hidden copies of other months' days. Useful in a popover.- isDateDisabled
MatcherReturnstruefor days that can't be picked or focused, such as weekends. Swapping the function works.- isDateUnavailable
MatcherReturnstruefor days that are struck through and can't be picked but stay focusable, such as fully booked ones. Swapping the function works.- isDateHighlightable
MatcherReturnstruefor unavailable days that the preview may still cross.- dir
DirectionThe reading direction, which also mirrors the arrow keys. Defaults to the one Reka UI'sConfigProvidersets.- nextPage
((placeholder: DateValue) => DateValue)Returns the placeholder Next moves to, for custom paging.- prevPage
((placeholder: DateValue) => DateValue)Returns the placeholder Previous moves to, for custom paging.- disableDaysOutsideCurrentView
booleanDisables the days from the neighbouring months. They still show with one month; seenumberOfMonths.- fixedDate
"start" | "end"Keeps thestartor theendin place while the other end is picked again.- asChild
booleanRender the single child instead of the root, merging the root's attributes onto it.- as
AsTag | ComponentThe element or component to render.- size
"md" CalendarSizeSets the day cells, arrows, gaps and text fromxstoxlon the [control scale](/docs/getting-started/sizing).md, 36px days, is the default.- color
"primary" CalendarColorThe tone of the selected day, the range's band and today's outline:primary,neutral,destructive,success,warning,info, or a name you define.- weekNumbers
booleanAdds a column of week numbers before each row, counted from the row's first day. Hidden from screen readers.- id
stringOverrides theidtaken from a surrounding field. The heading's id is built from it.
Emits
- update:modelValue
[date: DateRange]Fires when the range changes, including the partial{ start, end: undefined }while the end is being picked.- update:validModelValue
[date: DateRange]Fires once a range has both ends, in order. Listen to it to close a popover.- update:placeholder
[date: DateValue]Fires when the month on screen changes.- update:startValue
[date: DateValue | undefined]Fires when the start is picked, before there is an end.
Slots
- default
{ date: DateValue; grid: Grid<DateValue>[]; weekDays: string[]; weekStartsOn: WeekStartsOn; locale: string; fixedWeeks: boolean; modelValue: DateRange; }Replaces the built-in layout, with Reka's{ date, grid, weekDays, weekStartsOn, locale, fixedWeeks, modelValue }. Compose the parts in it.- heading
{ headingValue: string; date: DateValue; setPlaceholder: (date: DateValue) => void; }The heading's content, with{ headingValue, date, setPlaceholder }. Put month and year pickers here.- week-day
{ day: string; index: number; }A weekday header's content, with{ day, index }.- day
{ day: DateValue; dayValue: string; selected: boolean; today: boolean; disabled: boolean; unavailable: boolean; outsideView: boolean; outsideVisibleView: boolean; highlighted: boolean; highlightedStart: boolean; highlightedEnd: boolean; selectionStart: boolean; selectionEnd: boolean; }A day's content, with the Calendar fields plus{ highlighted, highlightedStart, highlightedEnd, selectionStart, selectionEnd }.- prev-icon
anyThe Previous arrow's icon, a chevron by default.- next-icon
anyThe Next arrow's icon, a chevron by default.
Props
- asChild
booleanRender the single child instead of a div, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The heading and the arrows.
Props
- asChild
booleanRender the single child instead of a div, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- id
stringOverrides the id the root gives the heading for itsaria-labelledby.
Slots
- default
{ headingValue: string; date: DateValue; setPlaceholder: (date: DateValue) => void; }The heading's content, with{ headingValue, date, setPlaceholder }.setPlaceholdermoves the view to a date's month without selecting it.
Props
- prevPage
((placeholder: DateValue) => DateValue)Returns the placeholder this button moves to, overriding the root'sprevPage.- asChild
booleanRender the single child instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, a chevron that flips in right-to-left layouts.
Props
- nextPage
((placeholder: DateValue) => DateValue)Returns the placeholder this button moves to, overriding the root'snextPage.- asChild
booleanRender the single child instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, a chevron that flips in right-to-left layouts.
Props
- asChild
booleanRender the single child instead of a table, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The head and body of one month.
Props
- asChild
booleanRender the single child instead of a thead, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The weekday row.
Props
- asChild
booleanRender the single child instead of a tbody, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The week rows.
Props
- asChild
booleanRender the single child instead of a tr, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}A week's cells, or the weekday headers.
Props
- asChild
booleanRender the single child instead of a th, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The weekday's name.
Props
- date*
DateValueThe day this cell holds.- asChild
booleanRender the single child instead of a td, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The day's trigger.
Props
- day*
DateValueThe day this trigger picks.- month*
DateValueThe month of the grid it sits in, which tells days from the neighbouring months apart.- asChild
booleanRender the single child instead of a div, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{ dayValue: string; disabled: boolean; selected: boolean; today: boolean; outsideView: boolean; outsideVisibleView: boolean; unavailable: boolean; highlighted: boolean; highlightedStart: boolean; highlightedEnd: boolean; selectionStart: boolean; selectionEnd: boolean; }The day's content, with the Calendar fields plus{ highlighted, highlightedStart, highlightedEnd, selectionStart, selectionEnd }.
Data attributes
The slots are Calendar's with a range- prefix. These differ:
| data-slot | Attributes | Description |
|---|---|---|
| range-calendar | data-size, data-color, data-months, data-disabled, data-readonly, data-invalid | The root, a role="group". data-invalid means an end is disabled. |
| range-calendar-cell | data-disabled, data-range-complete | A day's cell. It draws the band, in --tone-soft. data-range-complete is set once the range has both ends, even when one of them is in a month off screen. |
| range-calendar-cell-trigger | data-value, data-selected, data-selection-start, data-selection-end, data-highlighted, data-highlighted-start, data-highlighted-end, data-today, data-disabled, data-unavailable, data-outside-view | The day. data-selection-* mark the ends, data-highlighted* the preview while the end is picked. |
Accessibility
As on Calendar, with aria-pressed on the days in the range and aria-selected on their cells.
| Key | Action |
|---|---|
| ArrowLeft / ArrowRight / ArrowUp / ArrowDown | Moves by a day or a week, flipped in right-to-left. While the end is being picked, the preview follows. |
| Enter / Space | Picks the start, then the end. |
| Escape | In the middle of a pick, brings back the last complete range. Inside a popover it closes it too. |
| Home / End | Moves to the first or last day of the week. Needs reka-ui 2.11 or later. |
| PageUp / PageDown | Moves by a month, or by a year with Shift. Needs reka-ui 2.11 or later. |