alpha

RangeCalendar

RangeCalendars display a grid of days in one or more months and allow users to select a contiguous range of dates.

installyarn add @react-spectrum/calendar
version3.0.0-alpha.3
usageimport {RangeCalendar} from '@react-spectrum/calendar'
View repository
GitHub
View package
NPM

Example#

<RangeCalendar aria-label="Trip dates" />
<RangeCalendar aria-label="Trip dates" />
<RangeCalendar 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 (
    <Flex gap="size-300" wrap>
      <RangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-12')
        }} />
      <RangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}
import {parseDate} from '@internationalized/date';

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

  return (
    <Flex gap="size-300" wrap>
      <RangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-12')
        }} />
      <RangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}
import {parseDate} from '@internationalized/date';

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

  return (
    <Flex
      gap="size-300"
      wrap
    >
      <RangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start:
            parseDate(
              '2020-02-03'
            ),
          end: parseDate(
            '2020-02-12'
          )
        }}
      />
      <RangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue}
      />
    </Flex>
  );
}

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 Provider 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 {Provider} from '@adobe/react-spectrum';

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

import {Provider} from '@adobe/react-spectrum';

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

import {Provider} from '@adobe/react-spectrum';

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

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), the layout of the RangeCalendar is automatically flipped. Dates are automatically formatted using the current locale.

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 {getLocalTimeZone} from '@internationalized/date';
import {useDateFormatter} from '@adobe/react-spectrum';

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

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

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

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

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

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

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

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

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';

<RangeCalendar aria-label="Trip dates" minValue={today(getLocalTimeZone())} />
import {today} from '@internationalized/date';

<RangeCalendar
  aria-label="Trip dates"
  minValue={today(getLocalTimeZone())}
/>
import {today} from '@internationalized/date';

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

Props#

NameTypeDefaultDescription
visibleMonthsnumber1The number of months to display at once. Up to 3 months are supported.
minValueDateValue—The minimum allowed date that a user may select.
maxValueDateValue—The maximum allowed date that a user may select.
isDisabledbooleanfalseWhether the calendar is disabled.
isReadOnlybooleanfalseWhether the calendar value is immutable.
autoFocusbooleanfalseWhether to automatically focus the calendar when it mounts.
valueRangeValue—The current value (controlled).
defaultValueRangeValue—The default value (uncontrolled).
Events
NameTypeDefaultDescription
onChange( (value: RangeValue )) => void—Handler that is called when the value changes.
Layout
NameTypeDefaultDescription
flexResponsive<string | number | boolean>—When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>—When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>—When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<number | string>—When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>—Overrides the alignItems property of a flex or grid container. See MDN.
justifySelfResponsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>—Specifies how the element is justified inside a flex or grid container. See MDN.
orderResponsive<number>—The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>—When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>—When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>—When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>—When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>—When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>—When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>—When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDefaultDescription
marginResponsive<DimensionValue>—The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>—The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>—The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>—The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>—The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>—The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>—The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDefaultDescription
widthResponsive<DimensionValue>—The width of the element. See MDN.
minWidthResponsive<DimensionValue>—The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>—The maximum width of the element. See MDN.
heightResponsive<DimensionValue>—The height of the element. See MDN.
minHeightResponsive<DimensionValue>—The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>—The maximum height of the element. See MDN.
Positioning
NameTypeDefaultDescription
positionResponsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>—Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>—The top position for the element. See MDN.
bottomResponsive<DimensionValue>—The bottom position for the element. See MDN.
leftResponsive<DimensionValue>—The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>—The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>—The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>—The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>—The stacking order for the element. See MDN.
isHiddenResponsive<boolean>—Hides the element.
Accessibility
NameTypeDefaultDescription
idstring—The element's unique identifier. See MDN.
Advanced
NameTypeDefaultDescription
UNSAFE_classNamestring—Sets the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_styleCSSProperties—Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Disabled#

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

Read only#

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

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

Visible months#

By default, a RangeCalendar displays a single month. The visibleMonths prop allows displaying up to 3 months at a time.

<RangeCalendar aria-label="Trip dates" visibleMonths={3} />
<RangeCalendar aria-label="Trip dates" visibleMonths={3} />
<RangeCalendar
  aria-label="Trip dates"
  visibleMonths={3}
/>