# Calendar **Category**: react **URL**: https://www.heroui.com/docs/react/migration/calendar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/(components)/calendar.mdx > Migration guide for Calendar from HeroUI v2 to v3 *** Refer to the [v3 Calendar documentation](/docs/react/components/calendar) 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: ```tsx import { Calendar } from "@heroui/react"; export default function App() { return ; } ``` In v3, Calendar uses a compound component pattern with explicit subcomponents: ```tsx import { Calendar } from "@heroui/react"; export default function App() { return ( {(day) => {day}} {(date) => } ); } ``` ## 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 ```tsx import { Calendar } from "@heroui/react"; import { today, getLocalTimeZone } from "@internationalized/date"; ``` ```tsx import { Calendar } from "@heroui/react"; import { today, getLocalTimeZone } from "@internationalized/date"; {(day) => {day}} {(date) => } ``` ### Controlled State ```tsx import { useState } from "react"; import { Calendar } from "@heroui/react"; import { parseDate } from "@internationalized/date"; const [value, setValue] = useState(parseDate("2024-03-07")); ``` ```tsx import { useState } from "react"; import { Calendar } from "@heroui/react"; import { parseDate } from "@internationalized/date"; const [value, setValue] = useState(parseDate("2024-03-07")); {(day) => {day}} {(date) => } ``` ### Month and Year Pickers ```tsx ``` ```tsx {(day) => {day}} {(date) => } {(year) => } ``` ### Multiple Months ```tsx ``` ```tsx

{(day) => {day}} {(date) => } {(day) => {day}} {(date) => }

``` ### Unavailable Dates ```tsx import { isWeekend } from "@internationalized/date"; import { useLocale } from "@react-aria/i18n"; const { locale } = useLocale(); isWeekend(date, locale)} /> ``` ```tsx import { isWeekend } from "@internationalized/date"; import { useLocale } from "@react-aria/i18n"; const { locale } = useLocale(); isWeekend(date, locale)} > {(day) => {day}} {(date) => } ``` ### Top and Bottom Content ```tsx Select a date

} bottomContent={ } /> ``` ```tsx

Select a date

{(day) => {day}} {(date) => } ``` ### Cell Indicators ```tsx {/* v2 did not have a built-in cell indicator API */} ``` ```tsx {(day) => {day}} {(date) => ( {({formattedDate}) => ( <> {formattedDate} {hasEvent(date) && } )} )} ``` ## Styling Changes ### v2: `classNames` Prop ```tsx ``` ### v3: Direct `className` Props ```tsx {(day) => {day}} {(date) => } ``` ## Component Anatomy The v3 Calendar follows this structure: ``` Calendar (Root) ├── [Custom top content] ├── Calendar.Header │ ├── Calendar.Heading (or Calendar.YearPickerTrigger) │ ├── Calendar.NavButton slot="previous" │ └── Calendar.NavButton slot="next" ├── Calendar.Grid (one per visible month) │ ├── Calendar.GridHeader │ │ └── Calendar.HeaderCell (render prop) │ └── Calendar.GridBody │ └── Calendar.Cell (render prop) │ └── Calendar.CellIndicator (optional) ├── Calendar.YearPickerGrid (optional) │ └── Calendar.YearPickerGridBody │ └── Calendar.YearPickerCell └── [Custom bottom content] ``` ## Summary 1. **Component Structure**: Single component → compound components with explicit layout control 2. **Year Picker**: `showMonthAndYearPickers` prop → dedicated `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid` components 3. **Multiple Months**: `visibleMonths={n}` → `visibleDuration={{months: n}}` with multiple `Calendar.Grid` components using `offset` 4. **Color Removed**: Use Tailwind CSS classes instead 5. **Top/Bottom Content**: Props removed → place content directly as children inside `Calendar` 6. **Cell Customization**: New `Calendar.CellIndicator` and render prop support on `Calendar.Cell` 7. **Styling**: `classNames` prop → `className` on individual compound components 8. **Removed Props**: `calendarWidth`, `weekdayStyle`, `hideDisabledDates`, `disableAnimation` — use Tailwind CSS or omit