RangeCalendar

Migration guide for RangeCalendar from HeroUI v2 to v3

Refer to the v3 RangeCalendar documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, RangeCalendar was a single component configured entirely through props:

1import { RangeCalendar } from "@lenso/ui";2import { today, getLocalTimeZone } from "@internationalized/date";3
4export default function App() {5  return (6    <RangeCalendar7      aria-label="Trip dates"8      defaultValue={{9        start: today(getLocalTimeZone()),10        end: today(getLocalTimeZone()).add({ weeks: 1 }),11      }}12    />13  );14}

In v3, RangeCalendar uses a compound component pattern with explicit subcomponents:

1import { RangeCalendar } from "@lenso/ui";2import { today, getLocalTimeZone } from "@internationalized/date";3
4export default function App() {5  return (6    <RangeCalendar7      aria-label="Trip dates"8      defaultValue={{9        start: today(getLocalTimeZone()),10        end: today(getLocalTimeZone()).add({ weeks: 1 }),11      }}12    >13      <RangeCalendar.Header>14        <RangeCalendar.Heading />15        <RangeCalendar.NavButton slot="previous" />16        <RangeCalendar.NavButton slot="next" />17      </RangeCalendar.Header>18      <RangeCalendar.Grid>19        <RangeCalendar.GridHeader>20          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}21        </RangeCalendar.GridHeader>22        <RangeCalendar.GridBody>23          {(date) => <RangeCalendar.Cell date={date} />}24        </RangeCalendar.GridBody>25      </RangeCalendar.Grid>26    </RangeCalendar>27  );28}

Key Changes

1. Component Structure

v2: Single RangeCalendar component with all layout handled internally v3: Compound components: RangeCalendar.Header, RangeCalendar.Heading, RangeCalendar.NavButton, RangeCalendar.Grid, RangeCalendar.GridHeader, RangeCalendar.GridBody, RangeCalendar.HeaderCell, RangeCalendar.Cell, RangeCalendar.CellIndicator

2. Year Picker

v2: Built-in month/year pickers via showMonthAndYearPickers prop v3: Dedicated compound components: RangeCalendar.YearPickerTrigger, RangeCalendar.YearPickerGrid, RangeCalendar.YearPickerGridBody, RangeCalendar.YearPickerCell

3. Prop Changes

v2 Prop	v3 Equivalent	Notes
`value`	`value`	Same
`defaultValue`	`defaultValue`	Same
`onChange`	`onChange`	Same
`focusedValue`	`focusedValue`	Same
`onFocusChange`	`onFocusChange`	Same
`minValue`	`minValue`	Same
`maxValue`	`maxValue`	Same
`isDateUnavailable`	`isDateUnavailable`	Same
`allowsNonContiguousRanges`	`allowsNonContiguousRanges`	Same
`isDisabled`	`isDisabled`	Same
`isReadOnly`	`isReadOnly`	Same
`isInvalid`	`isInvalid`	Same
`pageBehavior`	`pageBehavior`	Same
`visibleMonths`	`visibleDuration`	Changed to `{months: number}` object
`showMonthAndYearPickers`	-	Use `RangeCalendar.YearPickerTrigger` and `RangeCalendar.YearPickerGrid`
`onHeaderExpandedChange`	`onYearPickerOpenChange`	Renamed
`color`	-	Removed (use Tailwind CSS)
`calendarWidth`	-	Removed (use `className` or Tailwind CSS)
`weekdayStyle`	-	Removed
`firstDayOfWeek`	-	Use `I18nProvider` locale instead
`topContent`	-	Place custom content inside `RangeCalendar` before the grid
`bottomContent`	-	Place custom content inside `RangeCalendar` after the grid
`errorMessage`	-	Removed (handle validation externally)
`showHelper`	-	Removed
`disableAnimation`	-	Removed
`classNames`	-	Use `className` on individual compound components

Migration Examples

Basic Range Selection

1import { RangeCalendar } from "@lenso/ui";2import { today, getLocalTimeZone } from "@internationalized/date";3
4<RangeCalendar5  aria-label="Trip dates"6  defaultValue={{7    start: today(getLocalTimeZone()),8    end: today(getLocalTimeZone()).add({ weeks: 1 }),9  }}10/>

Controlled State

1import { useState } from "react";2import { RangeCalendar } from "@lenso/ui";3import { parseDate } from "@internationalized/date";4
5const [value, setValue] = useState({6  start: parseDate("2024-03-01"),7  end: parseDate("2024-03-07"),8});9
10<RangeCalendar11  aria-label="Trip dates"12  value={value}13  onChange={setValue}14/>

Month and Year Pickers

1<RangeCalendar2  aria-label="Trip dates"3  showMonthAndYearPickers4/>

Multiple Months

1<RangeCalendar2  aria-label="Trip dates"3  visibleMonths={2}4/>

Unavailable Dates with Non-Contiguous Ranges

1import { isWeekend } from "@internationalized/date";2import { useLocale } from "@react-aria/i18n";3
4const { locale } = useLocale();5
6<RangeCalendar7  aria-label="Trip dates"8  isDateUnavailable={(date) => isWeekend(date, locale)}9  allowsNonContiguousRanges10/>

Styling Changes

v2: `classNames` Prop

1<RangeCalendar2  classNames={{3    base: "custom-base",4    prevButton: "custom-prev",5    nextButton: "custom-next",6    title: "custom-title",7    cell: "custom-cell",8    cellButton: "custom-cell-button",9  }}10/>

v3: Direct `className` Props

1<RangeCalendar className="custom-base">2  <RangeCalendar.Header>3    <RangeCalendar.Heading className="custom-title" />4    <RangeCalendar.NavButton slot="previous" className="custom-prev" />5    <RangeCalendar.NavButton slot="next" className="custom-next" />6  </RangeCalendar.Header>7  <RangeCalendar.Grid>8    <RangeCalendar.GridHeader>9      {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}10    </RangeCalendar.GridHeader>11    <RangeCalendar.GridBody>12      {(date) => <RangeCalendar.Cell date={date} className="custom-cell" />}13    </RangeCalendar.GridBody>14  </RangeCalendar.Grid>15</RangeCalendar>

Component Anatomy

The v3 RangeCalendar follows this structure:

1RangeCalendar (Root)2  ├── [Custom top content]3  ├── RangeCalendar.Header4  │   ├── RangeCalendar.Heading (or RangeCalendar.YearPickerTrigger)5  │   ├── RangeCalendar.NavButton slot="previous"6  │   └── RangeCalendar.NavButton slot="next"7  ├── RangeCalendar.Grid (one per visible month)8  │   ├── RangeCalendar.GridHeader9  │   │   └── RangeCalendar.HeaderCell (render prop)10  │   └── RangeCalendar.GridBody11  │       └── RangeCalendar.Cell (render prop)12  │           └── RangeCalendar.CellIndicator (optional)13  ├── RangeCalendar.YearPickerGrid (optional)14  │   └── RangeCalendar.YearPickerGridBody15  │       └── RangeCalendar.YearPickerCell16  └── [Custom bottom content]

Summary

Component Structure: Single component → compound components with explicit layout control
Year Picker: showMonthAndYearPickers prop → dedicated RangeCalendar.YearPickerTrigger and RangeCalendar.YearPickerGrid components
Multiple Months: visibleMonths={n} → visibleDuration={{months: n}} with multiple RangeCalendar.Grid components using offset
Color Removed: Use Tailwind CSS classes instead
Top/Bottom Content: Props removed → place content directly as children inside RangeCalendar
Cell Customization: New RangeCalendar.CellIndicator and render prop support on RangeCalendar.Cell
Styling: classNames prop → className on individual compound components
Removed Props: calendarWidth, weekdayStyle, showHelper, errorMessage, disableAnimation — use Tailwind CSS or handle externally