RangeCalendar

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

Usage

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

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

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

Anatomy

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

Examples

Disabled

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

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

Year Picker

RangeCalendar.YearPickerTrigger, RangeCalendar.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 { RangeCalendar } from "@lenso/ui";4import { RangeYearHeader, RangeGrid, RangeYearGrid } from "./demo-parts";5export function YearPicker() {6  return (7    <RangeCalendar aria-label="Trip dates">8      <RangeYearHeader />9      <RangeGrid />10      <RangeYearGrid />11    </RangeCalendar>12  );13}

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 { RangeCalendar } from "@lenso/ui";4import { parseDate } from "@internationalized/date";5import { RangeHeader, RangeGrid } from "./demo-parts";6export function DefaultValue() {7  return (8    <RangeCalendar9      aria-label="Trip dates"10      defaultValue={{ end: parseDate("2025-02-12"), start: parseDate("2025-02-03") }}11      firstDayOfWeek="mon"12    >13      <RangeHeader />14      <RangeGrid />15    </RangeCalendar>16  );17}

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

Controlled

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, RangeCalendar } from "@lenso/ui";4import {5  getLocalTimeZone,6  parseDate,7  startOfMonth,8  startOfWeek,9  today,10  type DateValue,11} from "@internationalized/date";12import { useState } from "react";13import { useLocale } from "react-aria-components/I18nProvider";14import * as stylex from "@stylexjs/stylex";15import { CalendarNote, layout } from "../calendar/demo-parts";16import { RangeHeader, RangeGrid } from "./demo-parts";17export function Controlled() {18  const [value, setValue] = useState<{ start: DateValue; end: DateValue } | null>(null);19  const [focusedDate, setFocusedDate] = useState<DateValue>(() => parseDate("2025-12-25"));20  const { locale } = useLocale();21  return (22    <div {...stylex.props(layout.stack)}>23      <ButtonGroup variant="tertiary">24        <Button onClick={() => setFocusedDate(today(getLocalTimeZone()))}>This week</Button>25        <Button26          onClick={() =>27            setFocusedDate(startOfWeek(today(getLocalTimeZone()).add({ weeks: 1 }), locale))28          }29        >30          Next week31        </Button>32        <Button33          onClick={() => setFocusedDate(startOfMonth(today(getLocalTimeZone()).add({ months: 1 })))}34        >35          Next month36        </Button>37      </ButtonGroup>38      <RangeCalendar39        aria-label="Trip dates"40        firstDayOfWeek="mon"41        focusedValue={focusedDate}42        value={value}43        onChange={setValue}44        onFocusChange={setFocusedDate}45      >46        <RangeHeader />47        <RangeGrid />48      </RangeCalendar>49      <CalendarNote>50        Selected range: {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(none)"}51      </CalendarNote>52      <div {...stylex.props(layout.controls)}>53        <Button54          size="sm"55          variant="secondary"56          onClick={() => {57            const start = today(getLocalTimeZone());58            setValue({ end: start.add({ days: 6 }), start });59            setFocusedDate(start);60          }}61        >62          Set 1 week63        </Button>64        <Button65          size="sm"66          variant="secondary"67          onClick={() => {68            const start = parseDate("2025-12-20");69            setValue({ end: parseDate("2025-12-31"), start });70            setFocusedDate(start);71          }}72        >73          Set Holidays74        </Button>75        <Button size="sm" variant="tertiary" onClick={() => setValue(null)}>76          Clear77        </Button>78      </div>79    </div>80  );81}

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 { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarNote, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function MinMaxDates() {9  const now = today(getLocalTimeZone());10  const maxDate = now.add({ months: 3 });11  return (12    <div {...stylex.props(layout.stack)}>13      <RangeCalendar aria-label="Trip dates" maxValue={maxDate} minValue={now}>14        <RangeHeader />15        <RangeGrid />16      </RangeCalendar>17      <CalendarNote>Select dates between today and {maxDate.toString()}</CalendarNote>18    </div>19  );20}

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 { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarNote, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function UnavailableDates() {9  const now = today(getLocalTimeZone());10  const blockedRanges = [11    [now.add({ days: 2 }), now.add({ days: 5 })],12    [now.add({ days: 12 }), now.add({ days: 13 })],13  ] as const;14  return (15    <div {...stylex.props(layout.stack)}>16      <RangeCalendar17        aria-label="Trip dates"18        defaultValue={{ end: now.add({ days: 9 }), start: now.add({ days: 6 }) }}19        firstDayOfWeek="mon"20        isDateUnavailable={(date) =>21          blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0)22        }23      >24        <RangeHeader />25        <RangeGrid />26      </RangeCalendar>27      <CalendarNote>Some days are unavailable</CalendarNote>28    </div>29  );30}

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

Anchor-Based Unavailable Dates

When selecting a range, isDateUnavailable receives a second argument, anchorDate, set to the first selected date. Use it to limit which end dates are valid (for example, within 7 days of the start).

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarNote, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function AnchorUnavailableDates() {9  return (10    <div {...stylex.props(layout.stack)}>11      <RangeCalendar12        aria-label="Trip dates"13        isDateUnavailable={(date, anchorDate) =>14          anchorDate != null && Math.abs(date.compare(anchorDate)) > 715        }16        minValue={today(getLocalTimeZone())}17      >18        <RangeHeader />19        <RangeGrid />20      </RangeCalendar>21      <CalendarNote>22        After selecting a start date, only dates within 7 days are available23      </CalendarNote>24    </div>25  );26}

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.

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

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 { RangeCalendar } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { DurationSelect, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function WeekView() {9  const [weeks, setWeeks] = useState(1);10  return (11    <div {...stylex.props(layout.controlsStack)}>12      <DurationSelect unit="weeks" value={weeks} onChange={setWeeks} />13      <RangeCalendar key={weeks} aria-label="Trip dates" visibleDuration={{ weeks }}>14        <RangeHeader />15        <RangeGrid />16      </RangeCalendar>17    </div>18  );19}

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 { RangeCalendar } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { DurationSelect, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function DayView() {9  const [days, setDays] = useState(5);10  return (11    <div {...stylex.props(layout.controlsStack)}>12      <DurationSelect unit="days" value={days} onChange={setDays} />13      <RangeCalendar key={days} aria-label="Trip dates" visibleDuration={{ days }}>14        <RangeHeader />15        <RangeGrid />16      </RangeCalendar>17    </div>18  );19}

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

Allows Non-Contiguous Ranges

Enable allowsNonContiguousRanges to allow selection across unavailable dates.

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarNote, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function AllowsNonContiguousRanges() {9  const now = today(getLocalTimeZone());10  const blockedRanges = [11    [now.add({ days: 2 }), now.add({ days: 5 })],12    [now.add({ days: 12 }), now.add({ days: 13 })],13  ] as const;14  return (15    <div {...stylex.props(layout.stack)}>16      <RangeCalendar17        allowsNonContiguousRanges18        aria-label="Trip dates"19        defaultValue={{ end: now.add({ days: 9 }), start: now.add({ days: 1 }) }}20        firstDayOfWeek="mon"21        isDateUnavailable={(date) =>22          blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0)23        }24      >25        <RangeHeader />26        <RangeGrid />27      </RangeCalendar>28      <CalendarNote>Non-contiguous ranges are allowed across unavailable dates</CalendarNote>29    </div>30  );31}

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 { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { CalendarNote, layout } from "../calendar/demo-parts";7import { RangeHeader, RangeGrid } from "./demo-parts";8export function ReadOnly() {9  const now = today(getLocalTimeZone());10  return (11    <div {...stylex.props(layout.stack)}>12      <RangeCalendar13        isReadOnly14        aria-label="Trip dates"15        defaultValue={{ start: now, end: now.add({ days: 4 }) }}16      >17        <RangeHeader />18        <RangeGrid />19      </RangeCalendar>20      <CalendarNote>Range calendar is read-only</CalendarNote>21    </div>22  );23}

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

Invalid

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, today, type DateValue } from "@internationalized/date";5import { useState } from "react";6import * as stylex from "@stylexjs/stylex";7import { CalendarNote, layout } from "../calendar/demo-parts";8import { RangeHeader, RangeGrid } from "./demo-parts";9const styles = stylex.create({ error: { fontSize: 14, color: "var(--danger)" } });10export function Invalid() {11  const now = today(getLocalTimeZone());12  const [value, setValue] = useState<{ start: DateValue; end: DateValue }>({13    end: now.add({ days: 14 }),14    start: now.add({ days: 6 }),15  });16  const isInvalid = value.end.compare(value.start) > 7;17  return (18    <div {...stylex.props(layout.stack)}>19      <RangeCalendar20        aria-label="Trip dates"21        firstDayOfWeek="mon"22        isInvalid={isInvalid}23        value={value}24        onChange={setValue}25      >26        <RangeHeader />27        <RangeGrid />28      </RangeCalendar>29      {isInvalid ? (30        <p {...stylex.props(styles.error)}>Maximum stay duration is 1 week</p>31      ) : (32        <CalendarNote>Select a stay of up to 7 days</CalendarNote>33      )}34    </div>35  );36}

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

Focused Value

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, RangeCalendar } from "@lenso/ui";4import { parseDate, type DateValue } from "@internationalized/date";5import { useState } from "react";6import * as stylex from "@stylexjs/stylex";7import { CalendarNote, layout } from "../calendar/demo-parts";8import { RangeHeader, RangeGrid } from "./demo-parts";9export function FocusedValue() {10  const [focusedDate, setFocusedDate] = useState<DateValue>(() => parseDate("2025-06-15"));11  return (12    <div {...stylex.props(layout.stack)}>13      <RangeCalendar14        aria-label="Trip dates"15        firstDayOfWeek="mon"16        focusedValue={focusedDate}17        onFocusChange={setFocusedDate}18      >19        <RangeHeader />20        <RangeGrid />21      </RangeCalendar>22      <CalendarNote>Focused: {focusedDate.toString()}</CalendarNote>23      <div {...stylex.props(layout.controls)}>24        <Button25          size="sm"26          variant="secondary"27          onClick={() => setFocusedDate(parseDate("2025-01-01"))}28        >29          Go to Jan30        </Button>31        <Button32          size="sm"33          variant="secondary"34          onClick={() => setFocusedDate(parseDate("2025-06-15"))}35        >36          Go to Jun37        </Button>38        <Button39          size="sm"40          variant="secondary"41          onClick={() => setFocusedDate(parseDate("2025-12-25"))}42        >43          Go to Christmas44        </Button>45      </div>46    </div>47  );48}

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

Cell Indicators

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

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

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, RangeCalendar } from "@lenso/ui";4import { getLocalTimeZone, isWeekend, today, type DateValue } from "@internationalized/date";5import { useState } from "react";6import { useLocale } from "react-aria-components/I18nProvider";7import * as stylex from "@stylexjs/stylex";8import { layout } from "../calendar/demo-parts";9import { RangeHeader, RangeGrid } from "./demo-parts";10const blockedDates = [5, 6, 12, 13, 14, 20];11export function BookingCalendar() {12  const [selectedRange, setSelectedRange] = useState<{ start: DateValue; end: DateValue } | null>(13    null,14  );15  const { locale } = useLocale();16  return (17    <div {...stylex.props(layout.stack)}>18      <RangeCalendar19        aria-label="Booking range"20        isDateUnavailable={(date) => isWeekend(date, locale) || blockedDates.includes(date.day)}21        minValue={today(getLocalTimeZone())}22        value={selectedRange}23        onChange={setSelectedRange}24      >25        <RangeHeader />26        <RangeGrid27          cell={(date) => (28            <RangeCalendar.Cell date={date}>29              {({ formattedDate, isUnavailable }) => (30                <>31                  {formattedDate}32                  {!isUnavailable &&33                    !isWeekend(date, locale) &&34                    blockedDates.includes(date.day) && <RangeCalendar.CellIndicator />}35                </>36              )}37            </RangeCalendar.Cell>38          )}39        />40      </RangeCalendar>41      <div {...stylex.props(layout.bookingDetails)}>42        <div {...stylex.props(layout.legend)}>43          <span {...stylex.props(layout.legendItem)}>44            <span {...stylex.props(layout.mutedDot)} /> Blocked dates45          </span>46          <span {...stylex.props(layout.legendItem)}>47            <span {...stylex.props(layout.defaultDot)} /> Weekend/Unavailable48          </span>49        </div>50        {selectedRange ? (51          <Button size="sm" variant="primary">52            Book {selectedRange.start.toString()} {"->"} {selectedRange.end.toString()}53          </Button>54        ) : null}55      </div>56    </div>57  );58}

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

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

International Calendars

By default, RangeCalendar displays dates using the calendar system for the user's locale. You can override this by wrapping your RangeCalendar 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 { RangeCalendar } from "@lenso/ui";4import { I18nProvider } from "react-aria-components/I18nProvider";5import { RangeYearHeader, RangeGrid, RangeYearGrid } from "./demo-parts";6export function InternationalCalendar() {7  return (8    <I18nProvider locale="hi-IN-u-ca-indian">9      <RangeCalendar aria-label="Trip dates">10        <RangeYearHeader />11        <RangeGrid />12        <RangeYearGrid />13      </RangeCalendar>14    </I18nProvider>15  );16}

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.

Customization

Tailwind CSS

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { RangeCalendar } from "@lenso/ui";4import { parseDate } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({8  root: {9    width: 252,10    borderRadius: "var(--radius-xl)",11    borderWidth: 1,12    borderStyle: "solid",13    borderColor: "color-mix(in oklab,var(--border) 80%,transparent)",14    backgroundColor: "var(--surface)",15    padding: 12,16    boxShadow:17      "0 1px 2px 0 rgb(0 0 0 / .05),0 0 0 1px color-mix(in oklab,var(--success) 10%,transparent)",18  },19  heading: { color: "var(--foreground)" },20  nav: {21    borderRadius: "var(--radius-md)",22    color: "var(--success)",23    backgroundColor: {24      default: "transparent",25      ":hover": "var(--success-soft)",26      ":is([data-hovered])": "var(--success-soft)",27    },28  },29  cell: {30    borderRadius: { default: "var(--radius-md)", ":is([data-selected])": 0 },31    borderTopLeftRadius: {32      default: "var(--radius-md)",33      ":is([data-selected])": 0,34      ":is([data-selection-start])": "var(--radius-md)",35    },36    borderBottomLeftRadius: {37      default: "var(--radius-md)",38      ":is([data-selected])": 0,39      ":is([data-selection-start])": "var(--radius-md)",40    },41    borderTopRightRadius: {42      default: "var(--radius-md)",43      ":is([data-selected])": 0,44      ":is([data-selection-end])": "var(--radius-md)",45    },46    borderBottomRightRadius: {47      default: "var(--radius-md)",48      ":is([data-selected])": 0,49      ":is([data-selection-end])": "var(--radius-md)",50    },51    backgroundColor: {52      default: null,53      ":is([data-selected])": "var(--success-soft)",54      ":is([data-selected][data-outside-month])":55        "color-mix(in oklab,var(--default) 20%,transparent)",56    },57  },58  button: {59    borderRadius: "var(--radius-md)",60    backgroundColor: {61      default: null,62      ":is([data-hovered]:not([data-selected]) > *)": "var(--default)",63      ":is([data-today] > *)": "var(--success-soft)",64      ":is([data-today][data-hovered]:not([data-selected]) > *)": "var(--success-soft-hover)",65      ":is([data-selection-start] > *,[data-selection-end] > *)": "var(--success)",66      ":is([data-selection-start][data-pressed] > *,[data-selection-end][data-pressed] > *)":67        "var(--success-hover)",68    },69    color: {70      default: null,71      ":is([data-today] > *)": "var(--success-soft-foreground)",72      ":is([data-selection-start] > *,[data-selection-end] > *)": "var(--success-foreground)",73    },74  },75});76export function CustomStyles() {77  return (78    <RangeCalendar79      aria-label="Hotel stay"80      xstyle={styles.root}81      defaultValue={{ end: parseDate("2025-02-14"), start: parseDate("2025-02-08") }}82      firstDayOfWeek="mon"83    >84      <RangeCalendar.Header>85        <RangeCalendar.Heading xstyle={styles.heading} />86        <RangeCalendar.NavButton xstyle={styles.nav} slot="previous" />87        <RangeCalendar.NavButton xstyle={styles.nav} slot="next" />88      </RangeCalendar.Header>89      <RangeCalendar.Grid>90        <RangeCalendar.GridHeader>91          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}92        </RangeCalendar.GridHeader>93        <RangeCalendar.GridBody>94          {(date) => (95            <RangeCalendar.Cell date={date} xstyle={styles.cell} buttonXstyle={styles.button} />96          )}97        </RangeCalendar.GridBody>98      </RangeCalendar.Grid>99    </RangeCalendar>100  );101}

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

Global CSS

1@layer components {2  .range-calendar {3    @apply w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm;4  }5
6  .range-calendar__heading {7    @apply text-sm font-semibold text-default;8  }9
10  .range-calendar__cell[data-selected="true"] .range-calendar__cell-button {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

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

.range-calendar - Root container.
.range-calendar__header - Header row containing nav buttons and heading.
.range-calendar__heading - Current month label.
.range-calendar__nav-button - Previous/next navigation controls.
.range-calendar__grid - Main day grid.
.range-calendar__grid-header - Weekday header row wrapper.
.range-calendar__grid-body - Date rows wrapper.
.range-calendar__header-cell - Weekday header cell.
.range-calendar__cell - Interactive day cell wrapper.
.range-calendar__cell-button - Interactive day button inside each cell.
.range-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

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

Selected: [data-selected="true"]
Selection start: [data-selection-start="true"]
Selection end: [data-selection-end="true"]
Range middle: [data-selection-in-range="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

RangeCalendar

RangeCalendar inherits all props from React Aria RangeCalendar.

Prop	Type	Default	Description
`value`	`RangeValue<DateValue> \| null`	-	Controlled selected range.
`defaultValue`	`RangeValue<DateValue> \| null`	-	Initial selected range (uncontrolled).
`onChange`	`(value: RangeValue<DateValue>) => 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, anchorDate: CalendarDate \| null) => boolean`	-	Marks dates as unavailable. When `anchorDate` is set, it is the first date the user selected in the current range gesture.
`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.
`allowsNonContiguousRanges`	`boolean`	`false`	Allows ranges that span unavailable dates.
`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
`RangeCalendar.Header`	Header container for navigation and heading.
`RangeCalendar.Heading`	Formatted heading for the visible range. Supports `offset` (for multi-month layouts) and `format` (month/year/day options).
`RangeCalendar.NavButton`	Previous/next navigation control (`slot="previous"` or `slot="next"`).
`RangeCalendar.Grid`	Day grid for one month (`offset` supported for multi-month layouts).
`RangeCalendar.GridHeader`	Weekday header container.
`RangeCalendar.GridBody`	Date cell body container.
`RangeCalendar.HeaderCell`	Weekday label cell.
`RangeCalendar.Cell`	Individual date cell.
`RangeCalendar.CellIndicator`	Optional indicator element for custom metadata.
`RangeCalendar.YearPickerTrigger`	Trigger to toggle year-picker mode.
`RangeCalendar.YearPickerTriggerHeading`	Localized heading content inside the year-picker trigger.
`RangeCalendar.YearPickerTriggerIndicator`	Toggle icon inside the year-picker trigger.
`RangeCalendar.YearPickerGrid`	Overlay year selection grid container.
`RangeCalendar.YearPickerGridBody`	Body renderer for year grid cells.
`RangeCalendar.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
`RangeCalendar.YearPickerTriggerHeading`	`format`	`DateFormatterOptions`	-	Customize month/year label (e.g. `{month: 'short'}`).
`RangeCalendar.YearPickerTriggerHeading`	`offset`	`{months?: number}`	-	Shift the heading relative to the focused date (multi-month layouts).
`RangeCalendar.YearPickerGrid`	`format`	`DateFormatterOptions`	`{year: 'numeric'}`	Customize year cell labels (era, calendar system, etc.).
`RangeCalendar.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.

RangeCalendar.Cell Render Props

When RangeCalendar.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.
`isSelectionStart`	`boolean`	Whether the date is the start of the selected range.
`isSelectionEnd`	`boolean`	Whether the date is the end of the selected range.
`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

Calendar

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

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

RangeCalendar

Usage

Anatomy

Examples

Disabled

Year Picker

Default Value

Controlled

Min and Max Dates

Unavailable Dates

Anchor-Based Unavailable Dates

Weeks in Month

Week View

Day View

Allows Non-Contiguous Ranges

Read Only

Invalid

Focused Value

Cell Indicators

Real-World Example

Multiple Months

International Calendars

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Interactive States

API Reference

RangeCalendar

Composition Parts

Year Picker Parts

RangeCalendar.Cell Render Props

Related packages

Related Components