Calendar

Migration guide for Calendar from HeroUI v2 to v3

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

Structure Changes

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

1import { Calendar } from "@lenso/ui";2
3export default function App() {4  return <Calendar aria-label="Date" />;5}

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

1import { Calendar } from "@lenso/ui";2
3export default function App() {4  return (5    <Calendar aria-label="Date">6      <Calendar.Header>7        <Calendar.Heading />8        <Calendar.NavButton slot="previous" />9        <Calendar.NavButton slot="next" />10      </Calendar.Header>11      <Calendar.Grid>12        <Calendar.GridHeader>13          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}14        </Calendar.GridHeader>15        <Calendar.GridBody>16          {(date) => <Calendar.Cell date={date} />}17        </Calendar.GridBody>18      </Calendar.Grid>19    </Calendar>20  );21}

Key Changes

1. Component Structure

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

2. Year Picker

v2: Built-in month/year pickers via showMonthAndYearPickers prop v3: Dedicated compound components: Calendar.YearPickerTrigger, Calendar.YearPickerGrid, Calendar.YearPickerGridBody, Calendar.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
`isDisabled`	`isDisabled`	Same
`isReadOnly`	`isReadOnly`	Same
`isInvalid`	`isInvalid`	Same
`visibleMonths`	`visibleDuration`	Changed to `{months: number}` object
`showMonthAndYearPickers`	-	Use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid`
`onHeaderExpandedChange`	`onYearPickerOpenChange`	Renamed
`color`	-	Removed (use Tailwind CSS)
`calendarWidth`	-	Removed (use `className` or Tailwind CSS)
`weekdayStyle`	-	Removed
`pageBehavior`	`pageBehavior`	Same
`firstDayOfWeek`	-	Use `I18nProvider` locale instead
`hideDisabledDates`	-	Removed
`disableAnimation`	-	Removed
`topContent`	-	Place custom content inside `Calendar` before `Calendar.Grid`
`bottomContent`	-	Place custom content inside `Calendar` after `Calendar.Grid`
`classNames`	-	Use `className` on individual compound components
`errorMessage`	-	Removed (handle validation externally)

4. Color Prop Removed

v2: color prop with default, primary, secondary, success, warning, danger v3: No color prop — style cells using Tailwind CSS classes or customize via calendar.css overrides

Migration Examples

Basic Calendar

1import { Calendar } from "@lenso/ui";2import { today, getLocalTimeZone } from "@internationalized/date";3
4<Calendar5  aria-label="Date"6  defaultValue={today(getLocalTimeZone())}7/>

Controlled State

1import { useState } from "react";2import { Calendar } from "@lenso/ui";3import { parseDate } from "@internationalized/date";4
5const [value, setValue] = useState(parseDate("2024-03-07"));6
7<Calendar8  aria-label="Date"9  value={value}10  onChange={setValue}11/>

Month and Year Pickers

1<Calendar2  aria-label="Date"3  showMonthAndYearPickers4/>

Multiple Months

1<Calendar2  aria-label="Date"3  visibleMonths={2}4/>

Unavailable Dates

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

Cell Indicators

1{/* v2 did not have a built-in cell indicator API */}

Styling Changes

v2: `classNames` Prop

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

Component Anatomy

The v3 Calendar follows this structure:

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

Summary

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