RangeCalendar

A range calendar displays one or more date grids and allows users to select a contiguous range of dates.

Theme

May 2026

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

isDisabled

commitBehavior

Example

RangeCalendar.tsx

RangeCalendar.css

Example

RangeCalendar.tsx

RangeCalendar.css

import {RangeCalendar} from './RangeCalendar';

<RangeCalendar />

Value

Use the value or defaultValue prop to set the selected date range, using objects in the @internationalized/date package. This library supports parsing date strings in multiple formats, manipulation across international calendar systems, time zones, etc.

February 2025

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	1

Selected range: February 3 – 12, 2025

import {parseDate, getLocalTimeZone} from '@internationalized/date';
import {useDateFormatter} from 'react-aria/useDateFormatter';
import {RangeCalendar} from './RangeCalendar';
import {useState} from 'react';

function Example() {
  let [range, setRange] = useState({
    start: parseDate('2025-02-03'),
    end: parseDate('2025-02-12')
  });
  let formatter = useDateFormatter({ dateStyle: 'long' });

  return (
    <>
      <RangeCalendar
        value={range}
        onChange={setRange}
      />
      <p>Selected range: {formatter.formatRange(
        range.start.toDate(getLocalTimeZone()),
        range.end.toDate(getLocalTimeZone())
      )}</p>
    </>
  );
}

International calendars

By default, RangeCalendar displays the value using the calendar system for the user's locale. Use <I18nProvider> to override the calendar system by setting the Unicode calendar locale extension. The onChange event always receives a date in the same calendar as the value or defaultValue (Gregorian if no value is provided), regardless of the displayed locale.

शक 1946 माघ

र	सो	मं	बु	गु	शु	श
29	30	1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30	1	2	3

Locale

Calendar

import {I18nProvider} from 'react-aria-components/I18nProvider';
import {parseDate} from '@internationalized/date';
import {RangeCalendar} from './RangeCalendar';

<I18nProvider locale="hi-IN-u-ca-indian">
  <RangeCalendar
    defaultValue={{
      start: parseDate('2025-02-03'),
      end: parseDate('2025-02-12')
    }} />
</I18nProvider>

Custom calendar systems

RangeCalendar also supports custom calendar systems that implement custom business rules, for example a fiscal year calendar that follows a 4-5-4 format, where month ranges don't follow the usual Gregorian calendar. See the @internationalized/date docs for an example implementation.

May 2026

S	M	T	W	T	F	S
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30

import type {AnyCalendarDate, Calendar} from '@internationalized/date';
import {CalendarDate, startOfWeek, GregorianCalendar} from '@internationalized/date';
import {RangeCalendar} from './RangeCalendar';

export default function Example() {
  return (
    <RangeCalendar
      firstDayOfWeek="sun"
      createCalendar={() => new Custom454()} />
  );
}

// See @internationalized/date docs linked above.
  // The anchor date, in Gregorian calendar.
  // The anchor date is a date that occurs in the first week of the first month of every fiscal year.
  anchorDate = new CalendarDate(2001, 2, 4);

  private getYear(year: number): [CalendarDate, number[]] {
    let anchor = this.anchorDate.set({year});
    let startOfYear = startOfWeek(anchor, 'en', 'sun');
    let isBigYear = !startOfYear.add({weeks: 53}).compare(anchor.add({years: 1}));
    let weekPattern = [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, isBigYear ? 5 : 4];
    return [startOfYear, weekPattern];
  }

  getDaysInMonth(date: AnyCalendarDate): number {
    let [, weekPattern] = this.getYear(date.year);
    return weekPattern[date.month - 1] * 7;
  }

  fromJulianDay(jd: number): CalendarDate {
    let gregorian = super.fromJulianDay(jd);
    let year = gregorian.year;

    let [monthStart, weekPattern] = this.getYear(year);
    if (gregorian.compare(monthStart) < 0) {
      year--;
      [monthStart, weekPattern] = this.getYear(year);
    }

    for (let month = 1; month <= 12; month++) {
      let weeks = weekPattern[month - 1];
      let nextMonth = monthStart.add({weeks});
      if (nextMonth.compare(gregorian) > 0) {
        let days = gregorian.compare(monthStart);
        return new CalendarDate(this, year, month, days + 1);
      }
      monthStart = nextMonth;
    }

    throw new Error('date not found');
  }

  toJulianDay(date: AnyCalendarDate): number {
    let [monthStart, weekPattern] = this.getYear(date.year);
    for (let month = 1; month < date.month; month++) {
      monthStart = monthStart.add({weeks: weekPattern[month - 1]});
    }

    let gregorian = monthStart.add({days: date.day - 1});
    return super.toJulianDay(gregorian);
  }

  getFormattableMonth(date: AnyCalendarDate): CalendarDate {
    let anchorMonth = this.anchorDate.month - 1;
    let dateMonth = date.month - 1;
    let month = ((anchorMonth + dateMonth) % 12) + 1;
    let year = anchorMonth + dateMonth >= 12 ? date.year + 1 : date.year;
    return new CalendarDate(year, month, 1);
  }

  isEqual(other: Calendar): boolean {
    return other instanceof Custom454 && other.anchorDate.compare(this.anchorDate) === 0;
  }
}

Validation

Use the minValue and maxValue props to set the valid date range. The isDateUnavailable callback prevents certain dates from being selected. Use allowsNonContiguousRanges to allow selecting ranges containing unavailable dates. For custom validation rules, set the isInvalid prop and the errorMessage slot.

Trip dates, June 2026

S	M	T	W	T	F	S
31	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	1	2	3	4

Maximum stay duration is 1 week

allowsNonContiguousRanges

import {today, getLocalTimeZone} from '@internationalized/date';
import {RangeCalendar} from './RangeCalendar';
import {useState} from 'react';

function Example(props) {
  let now = today(getLocalTimeZone());
  let [range, setRange] = useState({
    start: now.add({days: 6}),
    end: now.add({ days: 14 })
  });
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 15 }), now.add({ days: 17 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];
  let isInvalid = range.end.compare(range.start) > 7;

  return (
    <RangeCalendar
      {...props}
      aria-label="Trip dates"
      value={range}
      onChange={setRange}
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={(date, anchorDate) => (
        (anchorDate && Math.abs(date.compare(anchorDate)) > 7) ||
        disabledRanges.some((interval) =>
          date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
        )
      )}
      isInvalid={isInvalid}
      errorMessage={isInvalid ? 'Maximum stay duration is 1 week' : undefined} />
  );
}

Display options

Set the visibleDuration prop and render multiple CalendarGrid elements to display more than one month at a time. The pageBehavior prop controls whether pagination advances by a single month or multiple. The firstDayOfWeek and weeksInMonth props override the locale-specified defaults.

Trip dates, May to June 2026

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
31	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	1	2	3	4

visibleDuration

pageBehavior

firstDayOfWeek

weeksInMonth

import {RangeCalendar} from './RangeCalendar';

// TODO: move this into the starter example.
function Example(props) {
  return (
    <RangeCalendar
      {...props}
      aria-label="Trip dates"
      visibleDuration={{months: 2}}
    />
  );
}

Controlling the focused date

Use the focusedValue or defaultFocusedValue prop to control which date is focused. This controls which month is visible. The onFocusChange event is called when a date is focused by the user.

July 2021

S	M	T	W	T	F	S
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import {RangeCalendar} from './RangeCalendar';
import {Button} from './Button';
import {CalendarDate, today, getLocalTimeZone} from '@internationalized/date';
import {useState} from 'react';

function Example() {
  let defaultDate = new CalendarDate(2021, 7, 1);
  let [focusedDate, setFocusedDate] = useState(defaultDate);

  return (
    <div>
      <Button
        style={{marginBottom: 20}}
        onPress={() => setFocusedDate(today(getLocalTimeZone()))}>
        Today
      </Button>
      <RangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </div>
  );
}

Month and year pickers

Use the <CalendarMonthPicker> and <CalendarYearPicker> components to allow the user to jump to a different month or year. This example uses the render prop function to render a Select.

May 2026

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

import {RangeCalendar, CalendarMonthPicker, CalendarYearPicker} from 'react-aria-components/RangeCalendar';
import {CalendarGrid, CalendarCell} from './RangeCalendar';
import {Button} from './Button';
import {Select, SelectItem} from './Select';
import {ChevronLeft, ChevronRight} from 'lucide-react';

<RangeCalendar>
  <div className="months">
    <div className="month">
      <header style={{display: 'flex', gap: 4}}>
        <Button slot="previous" variant="quiet">
          <ChevronLeft />
        </Button>
        <CalendarMonthPicker>
          {(props) => (
            <Select {...props}>
              {item => <SelectItem>{item.formatted}</SelectItem>}
            </Select>
          )}
        </CalendarMonthPicker>
        <CalendarYearPicker>
          {(props) => (
            <Select {...props}>
              {item => <SelectItem>{item.formatted}</SelectItem>}
            </Select>
          )}
        </CalendarYearPicker>
        <Button slot="next" variant="quiet">
          <ChevronRight />
        </Button>
      </header>
      <CalendarGrid>
        {(date) => <CalendarCell date={date} />}
      </CalendarGrid>
    </div>
  </div>
</RangeCalendar>

API

<RangeCalendar>
  <CalendarHeading />
  <CalendarMonthPicker />
  <CalendarYearPicker />
  <Button slot="previous" />
  <Button slot="next" />
  <CalendarGrid>
    <CalendarGridHeader>
      {day => <CalendarHeaderCell />}
    </CalendarGridHeader>
    <CalendarGridBody>
      {date => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />
</RangeCalendar>

RangeCalendar

A range calendar displays one or more date grids and allows users to select a contiguous range of dates.

Name	Type	Default
`visibleDuration`	`DateDuration`	Default: `{ months: 1 }`
The amount of days that will be displayed at once. This affects how pagination works.
`createCalendar`	`(identifier: CalendarIdentifier) => Calendar`	Default: —
A function to create a new Calendar object for a given calendar identifier. If not provided, the `createCalendar` function from `@internationalized/date` will be used.
`commitBehavior`	`'clear' \| 'reset' \| 'select'`	Default: `'select'`
Controls the behavior when a pointer is released outside the calendar or a blur occurs mid selection: `clear`: clear the currently selected range of dates. `reset`: reset the selection to the previously selected range of dates. `select`: select the currently hovered range of dates.
`allowsNonContiguousRanges`	`boolean`	Default: —
When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`isDateUnavailable`	`(date: DateValue, anchorDate: CalendarDate \| null) => boolean`	Default: —
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. The second argument provides the current selection anchor date, if any. This can be used to adjust the available dates based on the user's first selected date.
`isDisabled`	`boolean`	Default: `false`
Whether the calendar is disabled.
`isReadOnly`	`boolean`	Default: `false`
Whether the calendar value is immutable.
`focusedValue`	`DateValue \| null`	Default: —
Controls the currently focused date within the calendar.
`defaultFocusedValue`	`DateValue \| null`	Default: —
The date that is focused when the calendar first mounts (uncontrolled).
`pageBehavior`	`PageBehavior`	Default: `visible`
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`firstDayOfWeek`	`'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'`	Default: —
The day that starts the week.
`selectionAlignment`	`'start' \| 'center' \| 'end'`	Default: `'center'`
Determines the alignment of the visible months on initial render based on the current selection or current date if there is no selection.
`weeksInMonth`	`number`	Default: —
The number of weeks in a month. This overrides the default set by the locale.
`children`	`ChildrenOrFunction<RangeCalendarRenderProps>`	Default: —
The children of the component. A function may be provided to alter the children based on component state.

`value`	`RangeValue<DateValue> \| null`	Default: —
The current value (controlled).
`defaultValue`	`RangeValue<DateValue> \| null`	Default: —
The default value (uncontrolled).
`onChange`	`(value: RangeValue<MappedDateValue<DateValue>>) => void`	Default: —
Handler that is called when the value changes.

Default className: react-aria-RangeCalendar

Render Prop	CSS Selector
`state`	CSS Selector: `—`
State of the range calendar.
`isDisabled`	CSS Selector: `[data-disabled]`
Whether the calendar is disabled.
`isInvalid`	CSS Selector: `[data-invalid]`
Whether the calendar is invalid.

CalendarGrid

A calendar grid displays a single grid of days within a calendar or range calendar which can be keyboard navigated and selected by the user.

Name	Type	Default
`children`	`ReactElement \| ReactElement[] \| (date: CalendarDate) => ReactElement`	Default: —
Either a function to render calendar cells for each date in the month, or children containing a <CalendarGridHeader>`` and<CalendarGridBody>` when additional customization is needed.
`offset`	`DateDuration`	Default: —
An offset from the beginning of the visible date range that this CalendarGrid should display. Useful when displaying more than one month at a time.
`weekdayStyle`	`'narrow' \| 'short' \| 'long'`	Default: `'narrow'`
The style of weekday names to display in the calendar grid header, e.g. single letter, abbreviation, or full day name.

Default className: react-aria-CalendarGrid

CalendarGridHeader

A calendar grid header displays a row of week day names at the top of a month.

Name	Type
`children`	`(day: string) => ReactElement`
A function to render a `<CalendarHeaderCell>` for a weekday name.

Default className: react-aria-CalendarGridHeader

CalendarHeaderCell

A calendar header cell displays a week day name at the top of a column within a calendar.

Name	Type
`children`	`ReactNode`
The children of the component.

Default className: react-aria-CalendarHeaderCell

CalendarGridBody

A calendar grid body displays a grid of calendar cells within a month.

Name	Type
`children`	`(date: CalendarDate) => ReactElement`
A function to render a `<CalendarCell>` for a given date.

Default className: react-aria-CalendarGridBody

CalendarCell

A calendar cell displays a date cell within a calendar grid which can be selected by the user.

Name	Type
`date`	`CalendarDate`
The date to render in the cell.
`children`	`ChildrenOrFunction<CalendarCellRenderProps>`
The children of the component. A function may be provided to alter the children based on component state.

Default className: react-aria-CalendarCell

Render Prop	CSS Selector
`date`	CSS Selector: `—`
The date that the cell represents.
`formattedDate`	CSS Selector: `—`
The day number formatted according to the current locale.
`isHovered`	CSS Selector: `[data-hovered]`
Whether the cell is currently hovered with a mouse.
`isPressed`	CSS Selector: `[data-pressed]`
Whether the cell is currently being pressed.
`isSelected`	CSS Selector: `[data-selected]`
Whether the cell is selected.
`isSelectionStart`	CSS Selector: `[data-selection-start]`
Whether the cell is the first date in a range selection.
`isSelectionEnd`	CSS Selector: `[data-selection-end]`
Whether the cell is the last date in a range selection.
`isFocused`	CSS Selector: `[data-focused]`
Whether the cell is focused.
`isFocusVisible`	CSS Selector: `[data-focus-visible]`
Whether the cell is keyboard focused.
`isDisabled`	CSS Selector: `[data-disabled]`
Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props. Disabled dates are not focusable, and cannot be selected by the user. They are typically displayed with a dimmed appearance.
`isOutsideVisibleRange`	CSS Selector: `[data-outside-visible-range]`
Whether the cell is outside the visible range of the calendar. For example, dates before the first day of a month in the same week.
`isOutsideMonth`	CSS Selector: `[data-outside-month]`
Whether the cell is outside the current month.
`isUnavailable`	CSS Selector: `[data-unavailable]`
Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough. Note that because they are focusable, unavailable dates must meet a 4.5:1 color contrast ratio, as defined by WCAG.
`isInvalid`	CSS Selector: `[data-invalid]`
Whether the cell is part of an invalid selection.
`isToday`	CSS Selector: `[data-today]`
Whether the cell is today.

CalendarHeading

Name	Type	Default
`offset`	`DateDuration`	Default: `0`
The number of months from the start of the visible range to display.
`format`	`CalendarHeadingFormatOptions`	Default: —
The format of the month heading.
`level`	`number`	Default: `3`
The heading level.

Default className: react-aria-CalendarHeading

CalendarMonthPicker

Name	Type
`children`	`(renderProps: CalendarMonthPickerAria) => JSX.Element`
A function to render the month picker.
`format`	`'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'`
The format of the month.

CalendarYearPicker

Name	Type	Default
`children`	`(renderProps: CalendarYearPickerAria) => JSX.Element`	Default: —
A function to render the year picker.
`visibleYears`	`number`	Default: `20`
The number of years to display.
`format`	`CalendarYearPickerFormatOptions`	Default: —
The format to display.

useRangeCalendar

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	1

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	1

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

RangeCalendar

Vanilla CSS theme

May 2026

Value

February 2025

International calendars

शक 1946 माघ

Custom calendar systems

May 2026

Validation

Trip dates, June 2026

Display options

Trip dates, May to June 2026

firstDayOfWeek

Controlling the focused date

July 2021

Month and year pickers

May 2026

API

RangeCalendar

CalendarGrid

CalendarGridHeader

CalendarHeaderCell

CalendarGridBody

CalendarCell

CalendarHeading

CalendarMonthPicker

CalendarYearPicker

Related pages

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	1

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6

S	M	T	W	T	F	S
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

S	M	T	W	T	F	S
26	27	28	29	30	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	1	2	3	4	5	6