# Calendar · HeroUI

> Composable date picker with month grid, navigation, and year picker support built on React Aria Calendar

- Page: https://jiguang132.com/systems/heroui/docs/components/calendar
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

```tsx
import { Calendar } from '@heroui/react';
```

### Usage


> Example `calendar-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Anatomy

```tsx
import {Calendar} from '@heroui/react';

export default () => (
  <Calendar aria-label="Event date">
    <Calendar.Header>
      <Calendar.Heading />
      <Calendar.NavButton slot="previous" />
      <Calendar.NavButton slot="next" />
    </Calendar.Header>
    <Calendar.Grid>
      <Calendar.GridHeader>
        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
      </Calendar.GridHeader>
      <Calendar.GridBody>
        {(date) => <Calendar.Cell date={date} />}
      </Calendar.GridBody>
    </Calendar.Grid>
  </Calendar>
)
```

### Year Picker

`Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.


> Example `calendar-year-picker`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Default Value


> Example `calendar-default-value`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Controlled

Use controlled `value` and `focusedValue` for external state coordination and custom shortcuts.


> Example `calendar-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Min and Max Dates


> Example `calendar-min-max-dates`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Unavailable Dates

Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots.


> Example `calendar-unavailable-dates`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Weeks in Month

Set `weeksInMonth` to a fixed value (for example, `6`) to keep the grid height stable when navigating between months. Use with care in non-Gregorian locales, similar to `firstDayOfWeek`.


> Example `calendar-weeks-in-month`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Week View

Set `visibleDuration={{ weeks: n }}` to show one or more weeks at a time. Navigation advances by the visible week range. Use `pageBehavior="single"` to move one week at a time when showing multiple weeks.


> Example `calendar-week-view`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Day View

Set `visibleDuration={{ days: n }}` to show a rolling window of consecutive days. Navigation advances by the visible day range. Use `pageBehavior="single"` to move one day at a time when showing multiple days.


> Example `calendar-day-view`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Multiple Selection

Set `selectionMode="multiple"` to let users select several dates. `value`, `defaultValue`, and `onChange` use an array of dates.


> Example `calendar-multiple-selection`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Disabled


> Example `calendar-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Read Only


> Example `calendar-read-only`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Focused Value

Programmatically control which date is focused using `focusedValue` and `onFocusChange`.


> Example `calendar-focused-value`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Cell Indicators

You can customize `Calendar.Cell` children and use `Calendar.CellIndicator` to display metadata like events.


> Example `calendar-with-indicators`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Multiple Months

Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `Calendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.


> Example `calendar-multiple-months`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### International Calendars

By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).

The example below shows the Indian calendar system:


> Example `calendar-international-calendar`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.

### Custom Navigation Icons

Pass children to `Calendar.NavButton` to replace the default chevron icons.


> Example `calendar-custom-icons`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Real-World Example


> Example `calendar-booking-calendar`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


### Custom Styles


> Example `calendar-custom-styles`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/calendar


## Styling

### Passing Tailwind CSS classes

```tsx
import {Calendar} from '@heroui/react';

function CustomCalendar() {
  return (
    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
      <Calendar.Header className="pb-3">
        <Calendar.Heading className="text-default" />
        <Calendar.NavButton slot="previous" className="text-default" />
        <Calendar.NavButton slot="next" className="text-default" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>
          {(date) => <Calendar.Cell date={date} />}
        </Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}
```

### Customizing the component classes

```css
@layer components {
  .calendar {
    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
  }

  .calendar__heading {
    @apply text-sm font-semibold text-default-700;
  }

  .calendar__cell[data-selected="true"] {
    @apply bg-accent text-accent-foreground;
  }
}
```

### CSS Classes

Calendar uses these classes in `packages/styles/components/calendar.css` and `packages/styles/components/calendar-year-picker.css`:

- `.calendar` - Root container.
- `.calendar__header` - Header row containing nav buttons and heading.
- `.calendar__heading` - Current month label.
- `.calendar__nav-button` - Previous/next navigation controls.
- `.calendar__grid` - Main day grid.
- `.calendar__grid-header` - Weekday header row wrapper.
- `.calendar__grid-body` - Date rows wrapper.
- `.calendar__header-cell` - Weekday header cell.
- `.calendar__cell` - Interactive day cell.
- `.calendar__cell-indicator` - Dot indicator inside a day cell.
- `.calendar-year-picker__trigger` - Year picker toggle button.
- `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger.
- `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger.
- `.calendar-year-picker__year-grid` - Overlay grid of selectable years.
- `.calendar-year-picker__year-cell` - Individual year option.

### Interactive States

Calendar supports both pseudo-classes and React Aria data attributes:

- **Selected**: `[data-selected="true"]`
- **Today**: `[data-today="true"]`
- **Unavailable**: `[data-unavailable="true"]`
- **Outside month**: `[data-outside-month="true"]`
- **Hovered**: `:hover` or `[data-hovered="true"]`
- **Pressed**: `:active` or `[data-pressed="true"]`
- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[data-disabled="true"]`

## API Reference

### Calendar Props

Calendar inherits all props from React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Whether one or many dates can be selected. |
| `value` | `DateValue \| null` or `DateValue[] \| null` | - | Controlled selected date(s). Use an array when `selectionMode` is `multiple`. |
| `defaultValue` | `DateValue \| null` or `DateValue[] \| null` | - | Initial selected date(s) (uncontrolled). |
| `onChange` | `(value: DateValue \| null)` or `(value: DateValue[] \| null) => void` | - | Called when selection changes. |
| `focusedValue` | `DateValue` | - | Controlled focused date. |
| `onFocusChange` | `(value: DateValue) => void` | - | Called when focus moves to another date. |
| `minValue` | `DateValue` | Calendar-aware `1900-01-01` | Earliest selectable date. |
| `maxValue` | `DateValue` | Calendar-aware `2099-12-31` | Latest selectable date. |
| `weeksInMonth` | `number` | - | The number of weeks in a month. This overrides the default set by the locale. |
| `isDateUnavailable` | `(date: DateValue) => boolean` | - | Marks dates as unavailable. |
| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | Overrides the locale default for the first day of the week. |
| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | Whether paging advances by the visible duration or one unit at a time. |
| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | Aligns the visible range to the selection on initial render. |
| `isDisabled` | `boolean` | `false` | Disables interaction and selection. |
| `isReadOnly` | `boolean` | `false` | Keeps content readable but prevents selection changes. |
| `isInvalid` | `boolean` | `false` | Marks the calendar as invalid for validation UI. |
| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | Visible time range. Use `{ months: n }` for month view, `{ weeks: n }` for week view, or `{ days: n }` for day view. |
| `defaultYearPickerOpen` | `boolean` | `false` | Initial open state of internal year picker. |
| `isYearPickerOpen` | `boolean` | - | Controlled year picker open state. |
| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | Called when year picker open state changes. |

### Composition Parts

| Component | Description |
|-----------|-------------|
| `Calendar.Header` | Header container for navigation and heading. |
| `Calendar.Heading` | Formatted heading for the visible range. Supports `offset` (for multi-month layouts) and `format` (month/year/day options). |
| `Calendar.NavButton` | Previous/next navigation control (`slot=\"previous\"` or `slot=\"next\"`). |
| `Calendar.Grid` | Day grid for one month (`offset` supported for multi-month layouts). |
| `Calendar.GridHeader` | Weekday header container. |
| `Calendar.GridBody` | Date cell body container. |
| `Calendar.HeaderCell` | Weekday label cell. |
| `Calendar.Cell` | Individual date cell. |
| `Calendar.CellIndicator` | Optional indicator element for custom metadata. |
| `Calendar.YearPickerTrigger` | Trigger to toggle year-picker mode. |
| `Calendar.YearPickerTriggerHeading` | Localized heading content inside the year-picker trigger. |
| `Calendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger. |
| `Calendar.YearPickerGrid` | Overlay year selection grid container. |
| `Calendar.YearPickerGridBody` | Body renderer for year grid cells. |
| `Calendar.YearPickerCell` | Individual year option cell. |

### Year Picker Parts

Year picker subcomponents inherit formatting props from React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) and [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker).

| Component | Prop | Type | Default | Description |
|-----------|------|------|---------|-------------|
| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | Customize month/year label (e.g. `{month: 'short'}`). |
| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | Shift the heading relative to the focused date (multi-month layouts). |
| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | Customize year cell labels (era, calendar system, etc.). |
| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max span or `20` | Number of years shown in the sliding window. Defaults to the full range between `minValue` and `maxValue` when both are set. |

### Calendar.Cell Render Props

When `Calendar.Cell` children is a function, React Aria render props are available:

| Prop | Type | Description |
|------|------|-------------|
| `formattedDate` | `string` | Localized day label for the cell. |
| `isSelected` | `boolean` | Whether the date is selected. |
| `isUnavailable` | `boolean` | Whether the date is unavailable. |
| `isDisabled` | `boolean` | Whether the cell is disabled. |
| `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. |

For a complete list of supported calendar systems and their identifiers, see:
- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

### Related packages
- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction

---

Index of all JGuang resources: https://jiguang132.com/llms.txt