Calendar

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

Usage

1import { Calendar } from '@lenso/ui';

1"use client";2
3/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */4import { Calendar } from "@lenso/ui";5
6export function Basic() {7  return (8    <Calendar aria-label="Event date">9      <Calendar.Header>10        <Calendar.Heading />11        <Calendar.NavButton slot="previous" />12        <Calendar.NavButton slot="next" />13      </Calendar.Header>14      <Calendar.Grid>15        <Calendar.GridHeader>16          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}17        </Calendar.GridHeader>18        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>19      </Calendar.Grid>20    </Calendar>21  );22}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

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

Examples

Disabled

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";7export function Disabled() {8  return (9    <div {...stylex.props(layout.stack)}>10      <Calendar isDisabled aria-label="Event date" defaultValue={today(getLocalTimeZone())}>11        <CalendarHeader />12        <CalendarGrid />13      </Calendar>14      <CalendarNote>Calendar is disabled</CalendarNote>15    </div>16  );17}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Read Only

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";7export function ReadOnly() {8  return (9    <div {...stylex.props(layout.stack)}>10      <Calendar isReadOnly aria-label="Event date" defaultValue={today(getLocalTimeZone())}>11        <CalendarHeader />12        <CalendarGrid />13      </Calendar>14      <CalendarNote>Calendar is read-only</CalendarNote>15    </div>16  );17}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Default Value

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4import { parseDate } from "@internationalized/date";5import { CalendarHeader, CalendarGrid } from "./demo-parts";6export function DefaultValue() {7  return (8    <Calendar aria-label="Event date" defaultValue={parseDate("2025-02-14")}>9      <CalendarHeader />10      <CalendarGrid />11    </Calendar>12  );13}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Year Picker

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4
5export function YearPicker() {6  return (7    <Calendar aria-label="Event date">8      <Calendar.Header>9        <Calendar.YearPickerTrigger>10          <Calendar.YearPickerTriggerHeading />11          <Calendar.YearPickerTriggerIndicator />12        </Calendar.YearPickerTrigger>13        <Calendar.NavButton slot="previous" />14        <Calendar.NavButton slot="next" />15      </Calendar.Header>16      <Calendar.Grid>17        <Calendar.GridHeader>18          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}19        </Calendar.GridHeader>20        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>21      </Calendar.Grid>22      <Calendar.YearPickerGrid>23        <Calendar.YearPickerGridBody>24          {({ year }) => <Calendar.YearPickerCell year={year} />}25        </Calendar.YearPickerGridBody>26      </Calendar.YearPickerGrid>27    </Calendar>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX and native Base UI Button. */3import { Button, ButtonGroup, Calendar } from "@lenso/ui";4import {5  getLocalTimeZone,6  parseDate,7  startOfMonth,8  startOfWeek,9  today,10  type CalendarDate,11} from "@internationalized/date";12import { useState } from "react";13import { useLocale } from "react-aria-components/I18nProvider";14import * as stylex from "@stylexjs/stylex";15import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";16export function Controlled() {17  const [value, setValue] = useState<CalendarDate | null>(null);18  const [focusedDate, setFocusedDate] = useState<CalendarDate>(() => parseDate("2025-12-25"));19  const { locale } = useLocale();20  const select = (date: CalendarDate) => {21    setValue(date);22    setFocusedDate(date);23  };24  return (25    <div {...stylex.props(layout.stack)}>26      <ButtonGroup fullWidth size="sm" variant="tertiary">27        <Button onClick={() => select(today(getLocalTimeZone()))}>Today</Button>28        <Button onClick={() => select(startOfWeek(today(getLocalTimeZone()), locale))}>Week</Button>29        <Button onClick={() => select(startOfMonth(today(getLocalTimeZone())))}>Month</Button>30      </ButtonGroup>31      <Calendar32        aria-label="Event date"33        focusedValue={focusedDate}34        value={value}35        onChange={setValue}36        onFocusChange={setFocusedDate}37      >38        <CalendarHeader />39        <CalendarGrid />40      </Calendar>41      <CalendarNote>Selected date: {value ? value.toString() : "(none)"}</CalendarNote>42      <div {...stylex.props(layout.controls)}>43        <Button size="sm" variant="secondary" onClick={() => select(today(getLocalTimeZone()))}>44          Set Today45        </Button>46        <Button size="sm" variant="secondary" onClick={() => select(parseDate("2025-12-25"))}>47          Set Christmas48        </Button>49        <Button size="sm" variant="tertiary" onClick={() => setValue(null)}>50          Clear51        </Button>52      </div>53    </div>54  );55}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Min and Max Dates

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";7export function MinMaxDates() {8  const now = today(getLocalTimeZone());9  const maxDate = now.add({ months: 3 });10  return (11    <div {...stylex.props(layout.stack)}>12      <Calendar aria-label="Appointment date" maxValue={maxDate} minValue={now}>13        <CalendarHeader />14        <CalendarGrid />15      </Calendar>16      <CalendarNote>Select a date between today and {maxDate.toString()}</CalendarNote>17    </div>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Unavailable Dates

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import { isWeekend } from "@internationalized/date";5import { useLocale } from "react-aria-components/I18nProvider";6import * as stylex from "@stylexjs/stylex";7import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";8export function UnavailableDates() {9  const { locale } = useLocale();10  return (11    <div {...stylex.props(layout.stack)}>12      <Calendar aria-label="Appointment date" isDateUnavailable={(date) => isWeekend(date, locale)}>13        <CalendarHeader />14        <CalendarGrid />15      </Calendar>16      <CalendarNote>Weekends are unavailable</CalendarNote>17    </div>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";6export function WeeksInMonth() {7  return (8    <div {...stylex.props(layout.stack)}>9      <Calendar aria-label="Event date" weeksInMonth={6}>10        <CalendarHeader />11        <CalendarGrid />12      </Calendar>13      <CalendarNote>14        Always shows 6 weeks per month to avoid layout shift when navigating15      </CalendarNote>16    </div>17  );18}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX and native Base UI Select. */3import { Calendar } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { CalendarHeader, CalendarGrid, DurationSelect, layout } from "./demo-parts";7export function WeekView() {8  const [weeks, setWeeks] = useState(1);9  return (10    <div {...stylex.props(layout.controlsStack)}>11      <DurationSelect unit="weeks" value={weeks} onChange={setWeeks} />12      <Calendar aria-label="Week view" visibleDuration={{ weeks }}>13        <CalendarHeader />14        <CalendarGrid />15      </Calendar>16    </div>17  );18}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX and native Base UI Select. */3import { Calendar } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { CalendarHeader, CalendarGrid, DurationSelect, layout } from "./demo-parts";7export function DayView() {8  const [days, setDays] = useState(5);9  return (10    <div {...stylex.props(layout.controlsStack)}>11      <DurationSelect unit="days" value={days} onChange={setDays} />12      <Calendar aria-label="Day view" visibleDuration={{ days }}>13        <CalendarHeader />14        <CalendarGrid />15      </Calendar>16    </div>17  );18}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Multiple Selection

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import type { DateValue } from "@internationalized/date";5import { useState } from "react";6import * as stylex from "@stylexjs/stylex";7import { CalendarNote } from "./demo-parts";8
9const styles = stylex.create({10  root: { display: "flex", flexDirection: "column", alignItems: "center", gap: 16 },11  description: { textAlign: "center" },12});13
14export function MultipleSelection() {15  const [value, setValue] = useState<readonly DateValue[]>([]);16  return (17    <div {...stylex.props(styles.root)}>18      <Calendar aria-label="Event dates" selectionMode="multiple" value={value} onChange={setValue}>19        <Calendar.Header>20          <Calendar.Heading />21          <Calendar.NavButton slot="previous" />22          <Calendar.NavButton slot="next" />23        </Calendar.Header>24        <Calendar.Grid>25          <Calendar.GridHeader>26            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}27          </Calendar.GridHeader>28          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>29        </Calendar.Grid>30      </Calendar>31      <CalendarNote>32        {value.length ? `${value.length} date(s) selected` : "Select multiple dates"}33      </CalendarNote>34    </div>35  );36}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Focused Value

Programmatically control which date is focused using focusedValue and onFocusChange.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX and native Base UI Button. */3import { Button, Calendar } from "@lenso/ui";4import { parseDate, type DateValue } from "@internationalized/date";5import { useState } from "react";6import * as stylex from "@stylexjs/stylex";7import { CalendarHeader, CalendarGrid, CalendarNote, layout } from "./demo-parts";8export function FocusedValue() {9  const [focusedDate, setFocusedDate] = useState<DateValue>(() => parseDate("2025-06-15"));10  return (11    <div {...stylex.props(layout.stack)}>12      <Calendar aria-label="Event date" focusedValue={focusedDate} onFocusChange={setFocusedDate}>13        <CalendarHeader />14        <CalendarGrid />15      </Calendar>16      <CalendarNote>Focused: {focusedDate.toString()}</CalendarNote>17      <div {...stylex.props(layout.controls)}>18        <Button19          size="sm"20          variant="secondary"21          onClick={() => setFocusedDate(parseDate("2025-01-01"))}22        >23          Go to Jan24        </Button>25        <Button26          size="sm"27          variant="secondary"28          onClick={() => setFocusedDate(parseDate("2025-06-15"))}29        >30          Go to Jun31        </Button>32        <Button33          size="sm"34          variant="secondary"35          onClick={() => setFocusedDate(parseDate("2025-12-25"))}36        >37          Go to Christmas38        </Button>39      </div>40    </div>41  );42}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Cell Indicators

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, isToday } from "@internationalized/date";5import { CalendarHeader, CalendarGrid } from "./demo-parts";6const datesWithEvents = [3, 7, 12, 15, 21, 28];7export function WithIndicators() {8  return (9    <Calendar aria-label="Event date">10      <CalendarHeader />11      <CalendarGrid12        cell={(date) => (13          <Calendar.Cell date={date}>14            {({ formattedDate }) => (15              <>16                {formattedDate}17                {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (18                  <Calendar.CellIndicator />19                )}20              </>21            )}22          </Calendar.Cell>23        )}24      />25    </Calendar>26  );27}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4import { CalendarGrid } from "./demo-parts";5export function CustomIcons() {6  return (7    <Calendar aria-label="Event date">8      <Calendar.Header>9        <Calendar.Heading />10        <Calendar.NavButton slot="previous">11          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">12            <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" />13          </svg>14        </Calendar.NavButton>15        <Calendar.NavButton slot="next">16          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">17            <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" />18          </svg>19        </Calendar.NavButton>20      </Calendar.Header>21      <CalendarGrid />22    </Calendar>23  );24}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Multiple Months

Render multiple grids with visibleDuration and offset for booking and planning experiences.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6const styles = stylex.create({7  root: { containerType: "normal", width: "100%", maxWidth: "none", overflowX: "auto" },8  months: { marginInline: "auto", display: "flex", width: "max-content", gap: 32 },9  month: { width: 256 },10  heading: { flex: "none" },11  spacer: { width: 24, height: 24 },12});13
14export function MultipleMonths() {15  return (16    <Calendar aria-label="Event date" xstyle={styles.root} visibleDuration={{ months: 2 }}>17      <div {...stylex.props(styles.months)}>18        <div {...stylex.props(styles.month)}>19          <Calendar.Header>20            <Calendar.NavButton slot="previous" />21            <Calendar.Heading xstyle={styles.heading} />22            <div {...stylex.props(styles.spacer)} />23          </Calendar.Header>24          <Calendar.Grid>25            <Calendar.GridHeader>26              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}27            </Calendar.GridHeader>28            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>29          </Calendar.Grid>30        </div>31        <div {...stylex.props(styles.month)}>32          <Calendar.Header>33            <div {...stylex.props(styles.spacer)} />34            <Calendar.Heading xstyle={styles.heading} offset={{ months: 1 }} />35            <Calendar.NavButton slot="next" />36          </Calendar.Header>37          <Calendar.Grid offset={{ months: 1 }}>38            <Calendar.GridHeader>39              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}40            </Calendar.GridHeader>41            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>42          </Calendar.Grid>43        </div>44      </div>45    </Calendar>46  );47}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Real-World Example

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX and native Base UI Button. */3import { Button, Calendar } from "@lenso/ui";4import { getLocalTimeZone, isWeekend, today, type CalendarDate } from "@internationalized/date";5import { useState } from "react";6import { useLocale } from "react-aria-components/I18nProvider";7import * as stylex from "@stylexjs/stylex";8import { CalendarHeader, CalendarGrid, layout } from "./demo-parts";9const bookedDates = [5, 6, 12, 13, 14, 20];10export function BookingCalendar() {11  const [selectedDate, setSelectedDate] = useState<CalendarDate | null>(null);12  const { locale } = useLocale();13  return (14    <div {...stylex.props(layout.stack)}>15      <Calendar16        aria-label="Booking date"17        isDateUnavailable={(date) => isWeekend(date, locale) || bookedDates.includes(date.day)}18        minValue={today(getLocalTimeZone())}19        value={selectedDate}20        onChange={setSelectedDate}21      >22        <CalendarHeader />23        <CalendarGrid24          cell={(date) => (25            <Calendar.Cell date={date}>26              {({ formattedDate, isUnavailable }) => (27                <>28                  {formattedDate}29                  {!isUnavailable && !isWeekend(date, locale) && bookedDates.includes(date.day) && (30                    <Calendar.CellIndicator />31                  )}32                </>33              )}34            </Calendar.Cell>35          )}36        />37      </Calendar>38      <div {...stylex.props(layout.bookingDetails)}>39        <div {...stylex.props(layout.legend)}>40          <span {...stylex.props(layout.legendItem)}>41            <span {...stylex.props(layout.mutedDot)} /> Has bookings42          </span>43          <span {...stylex.props(layout.legendItem)}>44            <span {...stylex.props(layout.defaultDot)} /> Weekend/Unavailable45          </span>46        </div>47        {selectedDate ? (48          <Button size="sm" variant="primary">49            Book {selectedDate.toString()}50          </Button>51        ) : null}52      </div>53    </div>54  );55}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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.

The example below shows the Indian calendar system:

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import { I18nProvider } from "react-aria-components/I18nProvider";6
7export function InternationalCalendar() {8  return (9    <I18nProvider locale="hi-IN-u-ca-indian">10      <Calendar aria-label="Event date" defaultValue={today(getLocalTimeZone())}>11        <Calendar.Header>12          <Calendar.YearPickerTrigger>13            <Calendar.YearPickerTriggerHeading />14            <Calendar.YearPickerTriggerIndicator />15          </Calendar.YearPickerTrigger>16          <Calendar.NavButton slot="previous" />17          <Calendar.NavButton slot="next" />18        </Calendar.Header>19        <Calendar.Grid>20          <Calendar.GridHeader>21            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}22          </Calendar.GridHeader>23          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>24        </Calendar.Grid>25        <Calendar.YearPickerGrid>26          <Calendar.YearPickerGridBody>27            {({ year }) => <Calendar.YearPickerCell year={year} />}28          </Calendar.YearPickerGridBody>29        </Calendar.YearPickerGrid>30      </Calendar>31    </I18nProvider>32  );33}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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.

Customization

Tailwind CSS

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { Calendar } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5
6const styles = stylex.create({7  root: {8    width: 252,9    borderRadius: "var(--radius-2xl)",10    borderWidth: 1,11    borderStyle: "solid",12    borderColor: {13      default: "color-mix(in oklab,var(--border) 80%,transparent)",14      ':is([data-theme="dark"] *)': "color-mix(in oklab,var(--border) 90%,transparent)",15    },16    backgroundColor: "var(--surface)",17    padding: 12,18    boxShadow: {19      default:20        "0 1px 2px 0 rgb(0 0 0 / .05), 0 0 0 1px color-mix(in oklab,var(--accent) 5%,transparent)",21      ':is([data-theme="dark"] *)':22        "0 1px 2px 0 rgb(0 0 0 / .05), 0 0 0 1px color-mix(in oklab,var(--accent) 10%,transparent)",23    },24  },25  heading: { color: "var(--foreground)" },26  cell: {27    backgroundColor: {28      default: null,29      ":hover": "var(--default)",30      ":is([data-hovered])": "var(--default)",31      ":is([data-selected])": "var(--accent)",32      ":is([data-selected]):is(:hover,[data-hovered])": "var(--accent-hover)",33      ":is([data-selected][data-outside-month])": "var(--default)",34      ":is([data-today])": "var(--accent-soft)",35      ":is([data-today]):is(:hover,[data-hovered])": "var(--accent-soft-hover)",36      ":is([data-selected][data-today])": "var(--accent)",37      ":is([data-selected][data-today]):hover": "var(--accent-hover)",38    },39    color: {40      default: null,41      ":is([data-outside-month])": "var(--muted)",42      ":is([data-selected])": "var(--accent-foreground)",43      ":is([data-today])": "var(--accent-soft-foreground)",44      ":is([data-selected][data-today])": "var(--accent-foreground)",45    },46  },47});48
49export function CustomStyles() {50  return (51    <Calendar aria-label="Custom styled calendar" xstyle={styles.root}>52      <Calendar.Header>53        <Calendar.Heading xstyle={styles.heading} />54        <Calendar.NavButton slot="previous" />55        <Calendar.NavButton slot="next" />56      </Calendar.Header>57      <Calendar.Grid>58        <Calendar.GridHeader>59          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}60        </Calendar.GridHeader>61        <Calendar.GridBody>62          {(date) => <Calendar.Cell xstyle={styles.cell} date={date} />}63        </Calendar.GridBody>64      </Calendar.Grid>65    </Calendar>66  );67}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

1@layer components {2  .calendar {3    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;4  }5
6  .calendar__heading {7    @apply text-sm font-semibold text-default-700;8  }9
10  .calendar__cell[data-selected="true"] {11    @apply bg-accent text-accent-foreground;12  }13}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

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

Calendar inherits all props from React Aria Calendar.

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 and 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:

@internationalized/date — date types (CalendarDate, CalendarDateTime, ZonedDateTime) and utilities used by all date components
I18nProvider — override locale for a subtree
useLocale — read the current locale and layout direction

RangeCalendar

Composable date range picker with month grid, navigation, and year picker support built on React Aria RangeCalendar

DateField

Date input field with labels, descriptions, and validation built on React Aria DateField

DatePicker

Composable date picker built on React Aria DatePicker with DateField and Calendar composition

Calendar

Usage

Anatomy

Examples

Disabled

Read Only

Default Value

Year Picker

Controlled

Min and Max Dates

Unavailable Dates

Weeks in Month

Week View

Day View

Multiple Selection

Focused Value

Cell Indicators

Custom Navigation Icons

Multiple Months

Real-World Example

International Calendars

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Interactive States

API Reference

Calendar

Composition Parts

Year Picker Parts

Calendar.Cell Render Props

Related packages

Related Components