RangeCalendar

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

Example#

import {Button, CalendarCell, CalendarGrid, Heading, RangeCalendar} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    {(date) => <CalendarCell date={date} />}
  </CalendarGrid>
</RangeCalendar>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  Heading,
  RangeCalendar
} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    {(date) => <CalendarCell date={date} />}
  </CalendarGrid>
</RangeCalendar>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  Heading,
  RangeCalendar
} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">
      ◀
    </Button>
    <Heading />
    <Button slot="next">
      ▶
    </Button>
  </header>
  <CalendarGrid>
    {(date) => (
      <CalendarCell
        date={date}
      />
    )}
  </CalendarGrid>
</RangeCalendar>

@import "@react-aria/example-theme";

.react-aria-RangeCalendar {
  width: fit-content;
  max-width: 100%;
  color: var(--text-color);

  & header {
    display: flex;
    align-items: center;
    margin: 0 4px .5rem 4px;

    .react-aria-Heading {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }
  }

  .react-aria-Button {
    width: 2rem;
    height: 2rem;
    padding: 0;
  }

  & table {
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;
    forced-color-adjust: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      border-radius: 0;

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -3px;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }
  }
}

@import "@react-aria/example-theme";

.react-aria-RangeCalendar {
  width: fit-content;
  max-width: 100%;
  color: var(--text-color);

  & header {
    display: flex;
    align-items: center;
    margin: 0 4px .5rem 4px;

    .react-aria-Heading {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }
  }

  .react-aria-Button {
    width: 2rem;
    height: 2rem;
    padding: 0;
  }

  & table {
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;
    forced-color-adjust: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      border-radius: 0;

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -3px;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }
  }
}

@import "@react-aria/example-theme";

.react-aria-RangeCalendar {
  width: fit-content;
  max-width: 100%;
  color: var(--text-color);

  & header {
    display: flex;
    align-items: center;
    margin: 0 4px .5rem 4px;

    .react-aria-Heading {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }
  }

  .react-aria-Button {
    width: 2rem;
    height: 2rem;
    padding: 0;
  }

  & table {
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;
    forced-color-adjust: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--gray-100);
    }

    &[data-focus-visible] {
      outline: 2px solid var(--highlight-background);
      outline-offset: -2px;
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
      border-radius: 0;

      &[data-focus-visible] {
        outline-color: var(--highlight-foreground);
        outline-offset: -3px;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }
  }
}

Features#

There is no standalone range calendar element in HTML. Two separate <input type="date"> elements could be used, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. RangeCalendar helps achieve accessible and international range calendar components that can be styled as needed.

• Flexible – Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
• International – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
• Accessible – Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.
• Touch friendly – Date ranges can be selected by dragging over dates in the calendar using a touch screen, and all interactions are accessible using touch-based screen readers.
• Customizable – As with all of React Aria, the DOM structure and styling of all elements can be fully customized.

Read our blog post for more details about the internationalization, accessibility, and user experience features implemented by RangeCalendar.

Anatomy#

A range calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating through time. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date range. Once a start date is selected, the user can navigate to another date using the keyboard or by hovering over it, and clicking it or pressing the Enter key commits the selected date range.

RangeCalendar also supports an optional error message element, which can be used to provide more context about any validation errors. This is linked with the calendar via the aria-describedby attribute.

import {Button, CalendarCell, CalendarGrid, CalendarGridBody, CalendarGridHeader, CalendarHeaderCell, Heading, RangeCalendar, Text} from 'react-aria-components';

<RangeCalendar>
  <Button slot="previous" />
  <Heading />
  <Button slot="next" />
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => <CalendarHeaderCell />}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />
</RangeCalendar>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  CalendarGridBody,
  CalendarGridHeader,
  CalendarHeaderCell,
  Heading,
  RangeCalendar,
  Text
} from 'react-aria-components';

<RangeCalendar>
  <Button slot="previous" />
  <Heading />
  <Button slot="next" />
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => <CalendarHeaderCell />}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />
</RangeCalendar>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  CalendarGridBody,
  CalendarGridHeader,
  CalendarHeaderCell,
  Heading,
  RangeCalendar,
  Text
} from 'react-aria-components';

<RangeCalendar>
  <Button slot="previous" />
  <Heading />
  <Button slot="next" />
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => (
        <CalendarHeaderCell />
      )}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />
</RangeCalendar>

Note that much of this anatomy is shared with non-range calendars. If you have both, the styling and internal components such as CalendarCell can be shared.

Concepts#

RangeCalendar makes use of the following concepts:

Composed components#

A Calendar uses the following components, which may also be used standalone or reused in other components.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Reusable wrappers#

If you will use a RangeCalendar in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

import type {DateValue, RangeCalendarProps} from 'react-aria-components';
import {Text} from 'react-aria-components';

interface MyRangeCalendarProps<T extends DateValue>
  extends RangeCalendarProps<T> {
  errorMessage?: string;
}

function MyRangeCalendar<T extends DateValue>(
  { errorMessage, ...props }: MyRangeCalendarProps<T>
) {
  return (
    <RangeCalendar {...props}>
      <header>
        <Button slot="previous">◀</Button>
        <Heading />
        <Button slot="next">▶</Button>
      </header>
      <CalendarGrid>
        {(date) => <CalendarCell date={date} />}
      </CalendarGrid>
      {errorMessage && <Text slot="errorMessage">{errorMessage}</Text>}
    </RangeCalendar>
  );
}

<MyRangeCalendar aria-label="Trip dates" />

import type {
  DateValue,
  RangeCalendarProps
} from 'react-aria-components';
import {Text} from 'react-aria-components';

interface MyRangeCalendarProps<T extends DateValue>
  extends RangeCalendarProps<T> {
  errorMessage?: string;
}

function MyRangeCalendar<T extends DateValue>(
  { errorMessage, ...props }: MyRangeCalendarProps<T>
) {
  return (
    <RangeCalendar {...props}>
      <header>
        <Button slot="previous">◀</Button>
        <Heading />
        <Button slot="next">▶</Button>
      </header>
      <CalendarGrid>
        {(date) => <CalendarCell date={date} />}
      </CalendarGrid>
      {errorMessage && (
        <Text slot="errorMessage">{errorMessage}</Text>
      )}
    </RangeCalendar>
  );
}

<MyRangeCalendar aria-label="Trip dates" />

import type {
  DateValue,
  RangeCalendarProps
} from 'react-aria-components';
import {Text} from 'react-aria-components';

interface MyRangeCalendarProps<
  T extends DateValue
> extends
  RangeCalendarProps<T> {
  errorMessage?: string;
}

function MyRangeCalendar<
  T extends DateValue
>(
  {
    errorMessage,
    ...props
  }: MyRangeCalendarProps<
    T
  >
) {
  return (
    <RangeCalendar
      {...props}
    >
      <header>
        <Button slot="previous">
          ◀
        </Button>
        <Heading />
        <Button slot="next">
          ▶
        </Button>
      </header>
      <CalendarGrid>
        {(date) => (
          <CalendarCell
            date={date}
          />
        )}
      </CalendarGrid>
      {errorMessage && (
        <Text slot="errorMessage">
          {errorMessage}
        </Text>
      )}
    </RangeCalendar>
  );
}

<MyRangeCalendar aria-label="Trip dates" />

Value#

A RangeCalendar has no selection by default. An initial, uncontrolled value can be provided to the RangeCalendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Date ranges are objects with start and end properties containing date values, which are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

RangeCalendar supports values with both date and time components, but only allows users to modify the dates. By default, RangeCalendar will emit CalendarDate objects in the onChange event, but if a CalendarDateTime or ZonedDateTime object is passed as the value or defaultValue, values of that type will be emitted, changing only the date and preserving the time components.

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState({
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-12')
  });

  return (
    <div style={{display: 'flex', gap: 20, flexWrap: 'wrap'}}>
      <MyRangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-12')
        }} />
      <MyRangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </div>
  );
}

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState({
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-12')
  });

  return (
    <div
      style={{ display: 'flex', gap: 20, flexWrap: 'wrap' }}
    >
      <MyRangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-12')
        }}
      />
      <MyRangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue}
      />
    </div>
  );
}

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] =
    React.useState({
      start: parseDate(
        '2020-02-03'
      ),
      end: parseDate(
        '2020-02-12'
      )
    });

  return (
    <div
      style={{
        display: 'flex',
        gap: 20,
        flexWrap: 'wrap'
      }}
    >
      <MyRangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start:
            parseDate(
              '2020-02-03'
            ),
          end: parseDate(
            '2020-02-12'
          )
        }}
      />
      <MyRangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue}
      />
    </div>
  );
}

International calendars#

RangeCalendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.

Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop. If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used. This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.

The below example displays a RangeCalendar in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.

import {I18nProvider} from 'react-aria';
import type {DateRange} from 'react-aria-components';

function Example() {
  let [range, setRange] = React.useState<DateRange | null>(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>Start date: {range?.start.toString()}</p>
      <p>End date: {range?.end.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';
import type {DateRange} from 'react-aria-components';

function Example() {
  let [range, setRange] = React.useState<DateRange | null>(
    null
  );
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>Start date: {range?.start.toString()}</p>
      <p>End date: {range?.end.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';
import type {DateRange} from 'react-aria-components';

function Example() {
  let [range, setRange] =
    React.useState<
      DateRange | null
    >(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Start date:{' '}
        {range?.start
          .toString()}
      </p>
      <p>
        End date:{' '}
        {range?.end
          .toString()}
      </p>
    </I18nProvider>
  );
}

Events#

RangeCalendar accepts an onChange prop which is triggered whenever a date is selected by the user. The example below uses onChange to update a separate element with a formatted version of the date in the user's locale. This is done by converting the date to a native JavaScript Date object to pass to the formatter.

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: parseDate('2020-07-03'),
    end: parseDate('2020-07-10')
  });
  let formatter = useDateFormatter({ dateStyle: 'long' });

  return (
    <>
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Selected date: {formatter.formatRange(
          range.start.toDate(getLocalTimeZone()),
          range.end.toDate(getLocalTimeZone())
        )}
      </p>
    </>
  );
}

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: parseDate('2020-07-03'),
    end: parseDate('2020-07-10')
  });
  let formatter = useDateFormatter({ dateStyle: 'long' });

  return (
    <>
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Selected date: {formatter.formatRange(
          range.start.toDate(getLocalTimeZone()),
          range.end.toDate(getLocalTimeZone())
        )}
      </p>
    </>
  );
}

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] =
    React.useState({
      start: parseDate(
        '2020-07-03'
      ),
      end: parseDate(
        '2020-07-10'
      )
    });
  let formatter =
    useDateFormatter({
      dateStyle: 'long'
    });

  return (
    <>
      <MyRangeCalendar
        aria-label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Selected date:
        {' '}
        {formatter
          .formatRange(
            range.start
              .toDate(
                getLocalTimeZone()
              ),
            range.end
              .toDate(
                getLocalTimeZone()
              )
          )}
      </p>
    </>
  );
}

Multi-month#

Multiple CalendarGrid elements can be rendered to show multiple months at once. The visibleDuration prop should be provided to the RangeCalendar component to specify how many months are visible, and each CalendarGrid accepts an offset prop to specify its starting date relative to the first visible date.

<RangeCalendar aria-label="Trip dates" visibleDuration={{months: 3}}>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <div style={{display: 'flex', gap: 30, overflow: 'auto'}}>
    <CalendarGrid>
      {date => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{months: 1}}>
      {date => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{months: 2}}>
      {date => <CalendarCell date={date} />}
    </CalendarGrid>
  </div>
</RangeCalendar>

<RangeCalendar
  aria-label="Trip dates"
  visibleDuration={{ months: 3 }}
>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <div
    style={{ display: 'flex', gap: 30, overflow: 'auto' }}
  >
    <CalendarGrid>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 1 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 2 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
  </div>
</RangeCalendar>

<RangeCalendar
  aria-label="Trip dates"
  visibleDuration={{
    months: 3
  }}
>
  <header>
    <Button slot="previous">
      ◀
    </Button>
    <Heading />
    <Button slot="next">
      ▶
    </Button>
  </header>
  <div
    style={{
      display: 'flex',
      gap: 30,
      overflow: 'auto'
    }}
  >
    <CalendarGrid>
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
    <CalendarGrid
      offset={{
        months: 1
      }}
    >
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
    <CalendarGrid
      offset={{
        months: 2
      }}
    >
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
  </div>
</RangeCalendar>

Page behavior#

The pageBehavior prop allows you to control how the calendar navigates between months. By default, the calendar will navigate by visibleDuration, but by setting pageBehavior to single, pagination will be by one month.

<RangeCalendar
  aria-label="Trip dates"
  visibleDuration={{ months: 3 }}
  pageBehavior="single"
>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <div style={{ display: 'flex', gap: 30, overflow: 'auto' }}>
    <CalendarGrid>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 1 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 2 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
  </div>
</RangeCalendar>

<RangeCalendar
  aria-label="Trip dates"
  visibleDuration={{ months: 3 }}
  pageBehavior="single"
>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <div
    style={{ display: 'flex', gap: 30, overflow: 'auto' }}
  >
    <CalendarGrid>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 1 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
    <CalendarGrid offset={{ months: 2 }}>
      {(date) => <CalendarCell date={date} />}
    </CalendarGrid>
  </div>
</RangeCalendar>

<RangeCalendar
  aria-label="Trip dates"
  visibleDuration={{
    months: 3
  }}
  pageBehavior="single"
>
  <header>
    <Button slot="previous">
      ◀
    </Button>
    <Heading />
    <Button slot="next">
      ▶
    </Button>
  </header>
  <div
    style={{
      display: 'flex',
      gap: 30,
      overflow: 'auto'
    }}
  >
    <CalendarGrid>
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
    <CalendarGrid
      offset={{
        months: 1
      }}
    >
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
    <CalendarGrid
      offset={{
        months: 2
      }}
    >
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGrid>
  </div>
</RangeCalendar>

Validation#

By default, RangeCalendar allows selecting any date range. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

import {today} from '@internationalized/date';

<MyRangeCalendar
  aria-label="Trip dates"
  minValue={today(getLocalTimeZone())}
/>

import {today} from '@internationalized/date';

<MyRangeCalendar
  aria-label="Trip dates"
  minValue={today(getLocalTimeZone())}
/>

import {today} from '@internationalized/date';

<MyRangeCalendar
  aria-label="Trip dates"
  minValue={today(
    getLocalTimeZone()
  )}
/>

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {
    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }
}

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {
    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }
}

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {
    &[data-disabled] {
      color: var(--text-color-disabled);
    }
  }
}

Unavailable dates#

RangeCalendar supports marking certain dates as unavailable. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.

Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected, enabled dates will be restricted to subsequent dates until an unavailable date is hit. See below for an example of how to allow non-contiguous ranges.

This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The minValue prop is also used to prevent selecting dates before today.

import {today} from '@internationalized/date';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];

  let isDateUnavailable = (date: DateValue) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
    );

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];

  let isDateUnavailable = (date: DateValue) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 &&
      date.compare(interval[1]) <= 0
    );

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let now = today(
    getLocalTimeZone()
  );
  let disabledRanges = [
    [
      now,
      now.add({
        days: 5
      })
    ],
    [
      now.add({
        days: 14
      }),
      now.add({
        days: 16
      })
    ],
    [
      now.add({
        days: 23
      }),
      now.add({
        days: 24
      })
    ]
  ];

  let isDateUnavailable =
    (date: DateValue) =>
      disabledRanges
        .some((
          interval
        ) =>
          date.compare(
              interval[0]
            ) >= 0 &&
          date.compare(
              interval[1]
            ) <= 0
        );

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      minValue={today(
        getLocalTimeZone()
      )}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }

    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }
}

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }

    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }
}

.react-aria-RangeCalendar {
  .react-aria-CalendarCell {

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }

    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }
}

Non-contiguous ranges#

The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.

import {useLocale} from 'react-aria';
import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } = useLocale();

  return (
    <MyRangeCalendar
      aria-label="Time off request"
      isDateUnavailable={(date) => isWeekend(date, locale)}
      allowsNonContiguousRanges
    />
  );
}

import {useLocale} from 'react-aria';
import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } = useLocale();

  return (
    <MyRangeCalendar
      aria-label="Time off request"
      isDateUnavailable={(date) => isWeekend(date, locale)}
      allowsNonContiguousRanges
    />
  );
}

import {useLocale} from 'react-aria';
import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } =
    useLocale();

  return (
    <MyRangeCalendar
      aria-label="Time off request"
      isDateUnavailable={(date) =>
        isWeekend(
          date,
          locale
        )}
      allowsNonContiguousRanges
    />
  );
}

Error message#

RangeCalendar tries to avoid allowing the user to select invalid dates in the first place (see Validation and Unavailable dates above). However, if according to application logic a selected date range is invalid, the isInvalid prop can be set. This alerts assistive technology users that the selection is invalid, and can be used for styling purposes as well. In addition, the errorMessage slot may be used to help the user fix the issue.

This example validates that the selected date range is a maximum of 1 week in duration.

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({ weeks: 1, days: 3 })
  });
  let isInvalid = range.end.compare(range.start) > 7;

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      value={range}
      onChange={setRange}
      isInvalid={isInvalid}
      errorMessage={isInvalid ? 'Maximum stay duration is 1 week' : undefined}    />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({
      weeks: 1,
      days: 3
    })
  });
  let isInvalid = range.end.compare(range.start) > 7;

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      value={range}
      onChange={setRange}
      isInvalid={isInvalid}
      errorMessage={isInvalid
        ? 'Maximum stay duration is 1 week'
        : undefined}    />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] =
    React.useState({
      start: today(
        getLocalTimeZone()
      ),
      end: today(
        getLocalTimeZone()
      ).add({
        weeks: 1,
        days: 3
      })
    });
  let isInvalid =
    range.end.compare(
      range.start
    ) > 7;

  return (
    <MyRangeCalendar
      aria-label="Trip dates"
      value={range}
      onChange={setRange}
      isInvalid={isInvalid}
      errorMessage={isInvalid
        ? 'Maximum stay duration is 1 week'
        : undefined}    />
  );
}

.react-aria-RangeCalendar {
  [slot=errorMessage] {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

.react-aria-RangeCalendar {
  [slot=errorMessage] {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

.react-aria-RangeCalendar {
  [slot=errorMessage] {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

Controlling the focused date#

By default, the first selected date is focused when a RangeCalendar first mounts. If no value or defaultValue prop is provided, then the current date is focused. However, RangeCalendar supports controlling which date is focused using the focusedValue and onFocusChange props. This also determines which month is visible. The defaultFocusedValue prop allows setting the initial focused date when the RangeCalendar first mounts, without controlling it.

This example focuses July 1, 2021 by default. The user may change the focused date, and the onFocusChange event updates the state. Clicking the button resets the focused date back to the initial value.

import {CalendarDate} from '@internationalized/date';

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

  return (
    <>
      <button
        style={{ marginBottom: 20 }}
        onClick={() => setFocusedDate(defaultDate)}
      >
        Reset focused date
      </button>
      <MyRangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </>
  );
}

import {CalendarDate} from '@internationalized/date';

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

  return (
    <>
      <button
        style={{ marginBottom: 20 }}
        onClick={() => setFocusedDate(defaultDate)}
      >
        Reset focused date
      </button>
      <MyRangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </>
  );
}

import {CalendarDate} from '@internationalized/date';

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

  return (
    <>
      <button
        style={{
          marginBottom:
            20
        }}
        onClick={() =>
          setFocusedDate(
            defaultDate
          )}
      >
        Reset focused
        date
      </button>
      <MyRangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </>
  );
}

Disabled#

The isDisabled boolean prop makes the RangeCalendar disabled. Cells cannot be focused or selected.

<MyRangeCalendar aria-label="Trip dates" isDisabled />

<MyRangeCalendar aria-label="Trip dates" isDisabled />

<MyRangeCalendar
  aria-label="Trip dates"
  isDisabled
/>

Read only#

The isReadOnly boolean prop makes the RangeCalendar's value immutable. Unlike isDisabled, the RangeCalendar remains focusable.

<MyRangeCalendar
  aria-label="Trip dates"
  value={{
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({ weeks: 1 })
  }}
  isReadOnly
/>

<MyRangeCalendar
  aria-label="Trip dates"
  value={{
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({ weeks: 1 })
  }}
  isReadOnly
/>

<MyRangeCalendar
  aria-label="Trip dates"
  value={{
    start: today(
      getLocalTimeZone()
    ),
    end: today(
      getLocalTimeZone()
    ).add({
      weeks: 1
    })
  }}
  isReadOnly
/>

Labeling#

An aria-label must be provided to the RangeCalendar for accessibility. If it is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a RangeCalendar, a localized string should be passed to the aria-label prop. For languages that are read right-to-left (e.g. Hebrew and Arabic), keyboard navigation is automatically flipped. Ensure that your CSS accounts for this as well. Dates are automatically formatted using the current locale.

Props#

RangeCalendar#

Heading#

A <Heading> accepts all HTML attributes.

Button#

A <Button> accepts its contents as children. Other props such as onPress and isDisabled will be set by the RangeCalendar.

CalendarGrid#

A <CalendarGrid> renders an individual month within a <RangeCalendar>. It accepts a function as its children, which is called to render a <CalendarCell> for each date. This renders a default <CalendarGridHeader>, which displays the weekday names in the column headers. This can be customized by providing a <CalendarGridHeader> and <CalendarGridBody> as children instead of a function.

CalendarGridHeader#

A <CalendarGridHeader> renders the header within a <CalendarGrid>, displaying a list of weekday names. It accepts a function as its children, which is called with a day name abbreviation to render a <CalendarHeaderCell> for each column header.

CalendarHeaderCell#

A <CalendarHeaderCell> renders a column header within a <CalendarGridHeader>. It typically displays a weekday name.

CalendarGridBody#

A <CalendarGridBody> renders the body within a <CalendarGrid>. It accepts a function as its children, which is called to render a <CalendarCell> for each date.

CalendarCell#

A <CalendarCell> renders an individual date within a <CalendarGrid>.

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-RangeCalendar {
  /* ... */
}

.react-aria-RangeCalendar {
  /* ... */
}

.react-aria-RangeCalendar {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<CalendarGrid className="my-calendar-grid">
  {/* ... */}
</CalendarGrid>

<CalendarGrid className="my-calendar-grid">
  {/* ... */}
</CalendarGrid>

<CalendarGrid className="my-calendar-grid">
  {/* ... */}
</CalendarGrid>

In addition, some components support multiple UI states (e.g. focused, placeholder, readonly, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:

.react-aria-CalendarCell[data-selected] {
  /* ... */
}

.react-aria-CalendarCell[data-invalid] {
  /* ... */
}

.react-aria-CalendarCell[data-selected] {
  /* ... */
}

.react-aria-CalendarCell[data-invalid] {
  /* ... */
}

.react-aria-CalendarCell[data-selected] {
  /* ... */
}

.react-aria-CalendarCell[data-invalid] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<CalendarCell
  className={({ isSelected }) => isSelected ? 'bg-blue-600' : 'bg-gray-600'}
/>

<CalendarCell
  className={({ isSelected }) =>
    isSelected ? 'bg-blue-600' : 'bg-gray-600'}
/>

<CalendarCell
  className={(
    { isSelected }
  ) =>
    isSelected
      ? 'bg-blue-600'
      : 'bg-gray-600'}
/>

Render props may also be used as children to alter what elements are rendered based on the current state. For example, you could add an additional element when a date is unavailable.

<CalendarCell>
  {({formattedDate, isUnavailable}) => (
    <>
      {isUnavailable && <UnavailableIcon />}
      <span>{formattedDate}</span>
    </>
  )}
</CalendarCell>

<CalendarCell>
  {({formattedDate, isUnavailable}) => (
    <>
      {isUnavailable && <UnavailableIcon />}
      <span>{formattedDate}</span>
    </>
  )}
</CalendarCell>

<CalendarCell>
  {(
    {
      formattedDate,
      isUnavailable
    }
  ) => (
    <>
      {isUnavailable &&
        (
          <UnavailableIcon />
        )}
      <span>
        {formattedDate}
      </span>
    </>
  )}
</CalendarCell>

The states, selectors, and render props for each component used in a RangeCalendar are documented below.

RangeCalendar#

A RangeCalendar can be targeted with the .react-aria-RangeCalendar CSS selector, or by overriding with a custom className. It supports the following states and render props:

Button#

A Button can be targeted with the .react-aria-Button CSS selector, or by overriding with a custom className. The next and previous buttons can be targeted specifically with the [slot=previous] and [slot=next] selectors. Buttons support the following states:

CalendarGrid#

A CalendarGrid can be targeted with the .react-aria-CalendarGrid CSS selector, or by overriding with a custom className. When a function is provided as children, a default <CalendarGridHeader> and <CalendarGridBody> are rendered. If you need to customize the styling of the header cells, you can render them yourself.

import {CalendarGridBody, CalendarGridHeader, CalendarHeaderCell} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => (
        <CalendarHeaderCell style={{ color: 'var(--blue)' }}>
          {day}
        </CalendarHeaderCell>
      )}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
</RangeCalendar>

import {
  CalendarGridBody,
  CalendarGridHeader,
  CalendarHeaderCell
} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => (
        <CalendarHeaderCell
          style={{ color: 'var(--blue)' }}
        >
          {day}
        </CalendarHeaderCell>
      )}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
</RangeCalendar>

import {
  CalendarGridBody,
  CalendarGridHeader,
  CalendarHeaderCell
} from 'react-aria-components';

<RangeCalendar aria-label="Trip dates">
  <header>
    <Button slot="previous">
      ◀
    </Button>
    <Heading />
    <Button slot="next">
      ▶
    </Button>
  </header>
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => (
        <CalendarHeaderCell
          style={{
            color:
              'var(--blue)'
          }}
        >
          {day}
        </CalendarHeaderCell>
      )}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => (
        <CalendarCell
          date={date}
        />
      )}
    </CalendarGridBody>
  </CalendarGrid>
</RangeCalendar>

CalendarGridHeader#

A CalendarGridHeader can be targeted with the .react-aria-CalendarGridHeader CSS selector, or by overriding with a custom className.

CalendarHeaderCell#

A CalendarHeaderCell can be targeted with the .react-aria-CalendarHeaderCell CSS selector, or by overriding with a custom className.

CalendarGridBody#

A CalendarGridBody can be targeted with the .react-aria-CalendarGridBody CSS selector, or by overriding with a custom className.

CalendarCell#

A CalendarCell can be targeted with the .react-aria-CalendarCell CSS selector, or by overriding with a custom className. It supports the following states:

Text#

The error message element within a RangeCalendar can be targeted with the [slot=errorMessage] CSS selector, or by adding a custom className.

Advanced customization#

Composition#

If you need to customize one of the components within a RangeCalendar, such as CalendarGrid or CalendarCell, in many cases you can create a wrapper component. This lets you customize the props passed to the component.

function MyCalendarCell(props) {
  return <CalendarCell {...props} className="my-item" />
}

function MyCalendarCell(props) {
  return <CalendarCell {...props} className="my-item" />
}

function MyCalendarCell(
  props
) {
  return (
    <CalendarCell
      {...props}
      className="my-item"
    />
  );
}

Contexts#

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in mergeProps).

This example uses RangeCalendarContext to create a composite component containing a calendar and buttons representing preset dates. The useSlottedContext hook can be used to consume contexts that support the slot prop.

import {RangeCalendarContext, useSlottedContext} from 'react-aria-components';

function CalendarPicker({ children }) {
  let [value, onChange] = React.useState(null);
  let [focusedValue, onFocusChange] = React.useState(null);

  return (
    <RangeCalendarContext.Provider
      value={{ value, onChange, focusedValue, onFocusChange }}
    >      <div className="calendar-picker">
        {children}
      </div>
    </RangeCalendarContext.Provider>
  );
}

interface PresetProps {
  value: { start: CalendarDate; end: CalendarDate };
  children: React.ReactNode;
}

function Preset({ value, children }: PresetProps) {
  let context = useSlottedContext(RangeCalendarContext)!;  let onPress = () => {
    context.onFocusChange(value.start);
    context.onChange(value);
  };

  return <Button onPress={onPress}>{children}</Button>;
}