RangeCalendar

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

install	`yarn add @react-spectrum/calendar`
version	3.0.0-rc.0
usage	`import {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()
  )}
/>

Unavailable dates#

RangeCalendar supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. 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';
import {useLocale} from '@adobe/react-spectrum';

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 { locale } = useLocale();
  let isDateUnavailable = (date) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
    );

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

import {today} from '@internationalized/date';
import {useLocale} from '@adobe/react-spectrum';

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 { locale } = useLocale();
  let isDateUnavailable = (date) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 &&
      date.compare(interval[1]) <= 0
    );

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

import {today} from '@internationalized/date';
import {useLocale} from '@adobe/react-spectrum';

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 { locale } =
    useLocale();
  let isDateUnavailable =
    (date) =>
      disabledRanges
        .some((
          interval
        ) =>
          date.compare(
              interval[0]
            ) >= 0 &&
          date.compare(
              interval[1]
            ) <= 0
        );

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

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 {isWeekend} from '@internationalized/date';

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

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

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

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

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

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

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

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

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 (
    <Flex direction="column" alignItems="start" gap="size-200">
      <ActionButton onPress={() => setFocusedDate(defaultDate)}>
        Reset focused date
      </ActionButton>
      <RangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </Flex>
  );
}

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

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

  return (
    <Flex
      direction="column"
      alignItems="start"
      gap="size-200"
    >
      <ActionButton
        onPress={() => setFocusedDate(defaultDate)}
      >
        Reset focused date
      </ActionButton>
      <RangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </Flex>
  );
}

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

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

  return (
    <Flex
      direction="column"
      alignItems="start"
      gap="size-200"
    >
      <ActionButton
        onPress={() =>
          setFocusedDate(
            defaultDate
          )}
      >
        Reset focused
        date
      </ActionButton>
      <RangeCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </Flex>
  );
}

Props#

Name	Type	Default	Description
`visibleMonths`	`number`	`1`	The number of months to display at once. Up to 3 months are supported.
`allowsNonContiguousRanges`	`boolean`	—	When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`minValue`	`DateValue`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`isDisabled`	`boolean`	`false`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	`false`	Whether the calendar value is immutable.
`autoFocus`	`boolean`	`false`	Whether to automatically focus the calendar when it mounts.
`focusedValue`	`DateValue`	—	Controls the currently focused date within the calendar.
`defaultFocusedValue`	`DateValue`	—	The date that is focused when the calendar first mounts (uncountrolled).
`validationState`	`ValidationState`	—	Whether the current selection is valid or invalid according to application logic.
`errorMessage`	`ReactNode`	—	An error message to display when the selected value is invalid.
`value`	`RangeValue<DateValue>`	—	The current value (controlled).
`defaultValue`	`RangeValue<DateValue>`	—	The default value (uncontrolled).

Events

Name	Type	Default	Description
`onFocusChange`	`( (date: CalendarDate )) => void`	—	Handler that is called when the focused date changes.
`onChange`	`( (value: RangeValue<MappedDateValue<DateValue>> )) => void`	—	Handler that is called when the value changes.

Layout

Name	Type	Default	Description
`flex`	`Responsive<string \| number \| boolean>`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'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.
`justifySelf`	`Responsive<'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.
`order`	`Responsive<number>`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`Responsive<DimensionValue>`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`Responsive<DimensionValue>`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`Responsive<DimensionValue>`	—	The width of the element. See MDN.
`minWidth`	`Responsive<DimensionValue>`	—	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	—	The maximum width of the element. See MDN.
`height`	`Responsive<DimensionValue>`	—	The height of the element. See MDN.
`minHeight`	`Responsive<DimensionValue>`	—	The minimum height of the element. See MDN.
`maxHeight`	`Responsive<DimensionValue>`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`Responsive<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	—	Specifies how the element is positioned. See MDN.
`top`	`Responsive<DimensionValue>`	—	The top position for the element. See MDN.
`bottom`	`Responsive<DimensionValue>`	—	The bottom position for the element. See MDN.
`left`	`Responsive<DimensionValue>`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`Responsive<DimensionValue>`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`Responsive<DimensionValue>`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`Responsive<DimensionValue>`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`Responsive<number>`	—	The stacking order for the element. See MDN.
`isHidden`	`Responsive<boolean>`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	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 RangeCalendar'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.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <RangeCalendar aria-label="Trip dates" visibleMonths={3} />
</div>

<div style={{ maxWidth: '100%', overflow: 'auto' }}>
  <RangeCalendar
    aria-label="Trip dates"
    visibleMonths={3}
  />
</div>

<div
  style={{
    maxWidth: '100%',
    overflow: 'auto'
  }}
>
  <RangeCalendar
    aria-label="Trip dates"
    visibleMonths={3}
  />
</div>

A CalendarDate represents a date without any time components in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDate`	Returns a copy of this date.
`add( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration added to it.
`subtract( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration subtracted from it.
`set( (fields: DateFields )): CalendarDate`	Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField, amount: number, options?: CycleOptions ): CalendarDate`	Returns a new `CalendarDate` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string )): Date`	Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: AnyCalendarDate )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

The Calendar interface represents a calendar system, including information about how days, months, years, and eras are organized, and methods to perform arithmetic on dates.

Properties

Name	Type	Description
`identifier`	`string`	A string identifier for the calendar, as defined by Unicode CLDR.

Methods

Method	Description
`fromJulianDay( (jd: number )): CalendarDate`	Creates a CalendarDate in this calendar from the given Julian day number.
`toJulianDay( (date: AnyCalendarDate )): number`	Converts a date in this calendar to a Julian day number.
`getDaysInMonth( (date: AnyCalendarDate )): number`	Returns the number of days in the month of the given date.
`getMonthsInYear( (date: AnyCalendarDate )): number`	Returns the number of months in the year of the given date.
`getYearsInEra( (date: AnyCalendarDate )): number`	Returns the number of years in the era of the given date.
`getEras(): string[]`	Returns a list of era identifiers for the calendar.
`getMinimumMonthInYear( (date: AnyCalendarDate )): number`	Returns the minimum month number of the given date's year. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a year.
`getMinimumDayInMonth( (date: AnyCalendarDate )): number`	Returns the minimum day number of the given date's month. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a month.

Name	Type	Description
`calendar`	`Calendar`
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

Method	Description
`copy():`

Represents an amount of time in calendar-specific units, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.

Name	Type	Description
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

'era'
  | 'year'
  | 'month'
  | 'day'

Name	Type	Description
`round`	`boolean`	Whether to round the field value to the nearest interval of the amount.

A CalendarDateTime represents a date and time without a time zone, in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): CalendarDateTime`	Returns a new `CalendarDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string, , disambiguation?: Disambiguation )): Date`	Converts the date to a native JavaScript Date object in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

Represents an amount of time with both date and time components, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.
`hours`	`number`	The number of hours to add or subtract.
`minutes`	`number`	The number of minutes to add or subtract.
`seconds`	`number`	The number of seconds to add or subtract.
`milliseconds`	`number`	The number of milliseconds to add or subtract.

Name	Type	Description
`hour`	`number`
`minute`	`number`
`second`	`number`
`millisecond`	`number`

'hour'
  | 'minute'
  | 'second'
  | 'millisecond'

Name	Type	Default	Description
`hourCycle`	`12 \| 24`	`24`	Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value will remain in the same day period as the original value (e.g. if the value is AM, the resulting value also be AM).
`round`	`boolean`	—	Whether to round the field value to the nearest interval of the amount.

'compatible'
  | 'earlier'
  | 'later'
  | 'reject'

A ZonedDateTime represents a date and time in a specific time zone and calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.
`timeZone`	`string`	The IANA time zone identifier that this date and time is represented in.
`offset`	`number`	The UTC offset for this time, in seconds.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): ZonedDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields, , disambiguation?: Disambiguation )): void`	Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `ZonedDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate(): void`	Converts the date to a native JavaScript Date object.
`toString(): void`	Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
`toAbsoluteString(): void`	Converts the date to an ISO 8601 formatted string in UTC.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): void`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

'valid' | 'invalid'

Name	Type	Description
`start`	`T`	The start value of the range.
`end`	`T`	The end value of the range.

DateValue extends ZonedDateTime ? ZonedDateTime :
DateValue extends CalendarDateTime ? CalendarDateTime :
DateValue extends CalendarDate ? CalendarDate : never

T | ResponsiveProp<T>

{base?: T,
S?: T,
M?: T,
L?: T,
[custom: string]: T | undefined
}

See the Styling docs for a visualization of these values.

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-130'
  | 'static-size-150'
  | 'static-size-160'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string
    &  & {}
  | number