Calendar

A calendar displays one or more date grids and allows users to select a single date.

install	`yarn add react-aria-components`
version	1.3.3
usage	`import {Calendar} from 'react-aria-components'`

View repository

GitHub

View package

NPM

Example#

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

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

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

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

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

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

Show CSS

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

.react-aria-Calendar {
  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;
  }

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

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

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

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

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

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

.react-aria-Calendar {
  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;
  }

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

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

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

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

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

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

.react-aria-Calendar {
  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;
  }

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

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

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

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

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

Features#

There is no standalone calendar element in HTML. <input type="date"> is close, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. Calendar helps achieve accessible and international 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.
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 Calendar.

Anatomy#

A calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating between date ranges. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date.

Calendar 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, Calendar, CalendarCell, CalendarGrid, CalendarGridBody, CalendarGridHeader, CalendarHeaderCell, Heading, Text} from 'react-aria-components';

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

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

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

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

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

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

Concepts#

Calendar makes use of the following concepts:

@internationalized/date

Represent and manipulate dates and times in a locale-aware manner.

Composed components#

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

Button

A button allows a user to perform an action.

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 Calendar 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.

This example also shows how to use the errorMessage slot to render help text in case of a validation error (see below for details).

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

interface MyCalendarProps<T extends DateValue> extends CalendarProps<T> {
  errorMessage?: string;
}

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

<MyCalendar aria-label="Event date" />

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

interface MyCalendarProps<T extends DateValue>
  extends CalendarProps<T> {
  errorMessage?: string;
}

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

<MyCalendar aria-label="Event date" />

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

interface MyCalendarProps<
  T extends DateValue
> extends
  CalendarProps<T> {
  errorMessage?: string;
}

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

<MyCalendar aria-label="Event date" />

Value#

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

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

Calendar supports values with both date and time components, but only allows users to modify the date. By default, Calendar 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(parseDate('2020-02-03'));

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

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

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

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

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

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

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

International calendars#

Calendar 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 Calendar in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.

import {I18nProvider} from 'react-aria';

function Example() {
  let [date, setDate] = React.useState<DateValue | null>(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyCalendar aria-label="Date" value={date} onChange={setDate} />
      <p>Selected date: {date?.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';

function Example() {
  let [date, setDate] = React.useState<DateValue | null>(
    null
  );
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyCalendar
        aria-label="Date"
        value={date}
        onChange={setDate}
      />
      <p>Selected date: {date?.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';

function Example() {
  let [date, setDate] =
    React.useState<
      DateValue | null
    >(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyCalendar
        aria-label="Date"
        value={date}
        onChange={setDate}
      />
      <p>
        Selected date:
        {' '}
        {date
          ?.toString()}
      </p>
    </I18nProvider>
  );
}

Events#

Calendar 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 [date, setDate] = React.useState(parseDate('2022-07-04'));
  let formatter = useDateFormatter({ dateStyle: 'full' });

  return (
    <>
      <MyCalendar aria-label="Event date" value={date} onChange={setDate} />
      <p>Selected date: {formatter.format(date.toDate(getLocalTimeZone()))}</p>
    </>
  );
}

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

function Example() {
  let [date, setDate] = React.useState(
    parseDate('2022-07-04')
  );
  let formatter = useDateFormatter({ dateStyle: 'full' });

  return (
    <>
      <MyCalendar
        aria-label="Event date"
        value={date}
        onChange={setDate}
      />
      <p>
        Selected date:{' '}
        {formatter.format(date.toDate(getLocalTimeZone()))}
      </p>
    </>
  );
}

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

function Example() {
  let [date, setDate] =
    React.useState(
      parseDate(
        '2022-07-04'
      )
    );
  let formatter =
    useDateFormatter({
      dateStyle: 'full'
    });

  return (
    <>
      <MyCalendar
        aria-label="Event date"
        value={date}
        onChange={setDate}
      />
      <p>
        Selected date:
        {' '}
        {formatter
          .format(
            date.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 Calendar 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.

<Calendar aria-label="Appointment date" 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>
</Calendar>

<Calendar
  aria-label="Appointment date"
  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>
</Calendar>

<Calendar
  aria-label="Appointment date"
  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>
</Calendar>

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.

<Calendar
  aria-label="Appointment date"
  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>
</Calendar>

<Calendar
  aria-label="Appointment date"
  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>
</Calendar>

<Calendar
  aria-label="Appointment date"
  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>
</Calendar>

Validation#

By default, Calendar allows selecting any date. 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';

<MyCalendar
  aria-label="Appointment date"
  minValue={today(getLocalTimeZone())}
/>

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

<MyCalendar
  aria-label="Appointment date"
  minValue={today(getLocalTimeZone())}
/>

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

<MyCalendar
  aria-label="Appointment date"
  minValue={today(
    getLocalTimeZone()
  )}
/>

Show CSS

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

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

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

Unavailable dates#

Calendar 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.

This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The minValue prop is also used to prevent selecting dates before today.

import {useLocale} from 'react-aria';
import {isWeekend, 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 { locale } = useLocale();
  let isDateUnavailable = (date: DateValue) =>
    isWeekend(date, locale) ||
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
    );

  return (
    <MyCalendar
      aria-label="Appointment date"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

import {useLocale} from 'react-aria';
import {isWeekend, 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 { locale } = useLocale();
  let isDateUnavailable = (date: DateValue) =>
    isWeekend(date, locale) ||
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 &&
      date.compare(interval[1]) <= 0
    );

  return (
    <MyCalendar
      aria-label="Appointment date"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

import {useLocale} from 'react-aria';
import {
  isWeekend,
  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 { locale } =
    useLocale();
  let isDateUnavailable =
    (date: DateValue) =>
      isWeekend(
        date,
        locale
      ) ||
      disabledRanges
        .some((
          interval
        ) =>
          date.compare(
              interval[0]
            ) >= 0 &&
          date.compare(
              interval[1]
            ) <= 0
        );

  return (
    <MyCalendar
      aria-label="Appointment date"
      minValue={today(
        getLocalTimeZone()
      )}
      isDateUnavailable={isDateUnavailable}
    />
  );
}

Show CSS

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }
  }
}

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }
  }
}

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--invalid-color);
    }
  }
}

Error message#

Calendar 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 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 is a weekday and not a weekend according to the current locale.

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

function Example() {
  let [date, setDate] = React.useState(today(getLocalTimeZone()));
  let {locale} = useLocale();
  let isInvalid = isWeekend(date, locale);

  return (
    <MyCalendar
      aria-label="Appointment date"
      value={date}
      onChange={setDate}
      isInvalid={isInvalid}
      errorMessage={isInvalid ? 'We are closed on weekends' : undefined}    />
  );
}

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

function Example() {
  let [date, setDate] = React.useState(
    today(getLocalTimeZone())
  );
  let { locale } = useLocale();
  let isInvalid = isWeekend(date, locale);

  return (
    <MyCalendar
      aria-label="Appointment date"
      value={date}
      onChange={setDate}
      isInvalid={isInvalid}
      errorMessage={isInvalid
        ? 'We are closed on weekends'
        : undefined}    />
  );
}

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

function Example() {
  let [date, setDate] =
    React.useState(
      today(
        getLocalTimeZone()
      )
    );
  let { locale } =
    useLocale();
  let isInvalid =
    isWeekend(
      date,
      locale
    );

  return (
    <MyCalendar
      aria-label="Appointment date"
      value={date}
      onChange={setDate}
      isInvalid={isInvalid}
      errorMessage={isInvalid
        ? 'We are closed on weekends'
        : undefined}    />
  );
}

Show CSS

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }

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

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }

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

.react-aria-Calendar {
  .react-aria-CalendarCell {
    &[data-invalid] {
      background: var(--invalid-color);
      color: var(--highlight-foreground);
    }
  }

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

Controlling the focused date#

By default, the selected date is focused when a Calendar first mounts. If no value or defaultValue prop is provided, then the current date is focused. However, Calendar 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 Calendar 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>
      <MyCalendar 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>
      <MyCalendar
        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>
      <MyCalendar
        focusedValue={focusedDate}
        onFocusChange={setFocusedDate}
      />
    </>
  );
}

Disabled#

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

<MyCalendar aria-label="Event date" isDisabled />

<MyCalendar aria-label="Event date" isDisabled />

<MyCalendar
  aria-label="Event date"
  isDisabled
/>

Read only#

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

<MyCalendar
  aria-label="Event date"
  value={today(getLocalTimeZone())}
  isReadOnly
/>

<MyCalendar
  aria-label="Event date"
  value={today(getLocalTimeZone())}
  isReadOnly
/>

<MyCalendar
  aria-label="Event date"
  value={today(
    getLocalTimeZone()
  )}
  isReadOnly
/>

Labeling#

An aria-label must be provided to the Calendar 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 Calendar, 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#

Calendar#

Name	Type	Default	Description
`visibleDuration`	`DateDuration`	`{months: 1}`	The amount of days that will be displayed at once. This affects how pagination works.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	—	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).
`isInvalid`	`boolean`	—	Whether the current selection is invalid according to application logic.
`pageBehavior`	`PageBehavior`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`value`	`DateValue \| null`	—	The current value (controlled).
`defaultValue`	`DateValue \| null`	—	The default value (uncontrolled).
`children`	`ReactNode \| ( (values: CalendarRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: CalendarRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: CalendarRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

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

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

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 Calendar.

Show props

Name	Type	Default	Description
`form`	`string`	—	The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document.
`formAction`	`string`	—	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
`formEncType`	`string`	—	Indicates how to encode the form data that is submitted.
`formMethod`	`string`	—	Indicates the HTTP method used to submit the form.
`formNoValidate`	`boolean`	—	Indicates that the form is not to be validated when it is submitted.
`formTarget`	`string`	—	Overrides the target attribute of the button's form owner.
`name`	`string`	—	Submitted as a pair with the button's value as part of the form data.
`value`	`string`	—	The value associated with the button's name when it's submitted with the form data.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`children`	`ReactNode \| ( (values: ButtonRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ButtonRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ButtonRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onPress`	`( (e: PressEvent )) => void`	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`excludeFromTabOrder`	`boolean`	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`aria-expanded`	`boolean \| 'true' \| 'false'`	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	Indicates the current "pressed" state of toggle buttons.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

CalendarGrid#

A <CalendarGrid> renders an individual month within a <Calendar>. 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.

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

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.

Show props

Name	Type	Description
`children`	`( (day: string )) => ReactElement`	A function to render a `<CalendarHeaderCell>` for a weekday name.
`className`	`string`	The CSS className for the element.
`style`	`CSSProperties`	The inline style for the element.

CalendarHeaderCell#

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

Show props

Name	Type	Description
`children`	`ReactNode`	The children of the component.
`className`	`string`	The CSS className for the element.
`style`	`CSSProperties`	The inline style for the element.

Accessibility

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

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.

Show props

Name	Type	Description
`children`	`( (date: CalendarDate )) => ReactElement`	A function to render a `<CalendarCell>` for a given date.
`className`	`string`	The CSS className for the element.
`style`	`CSSProperties`	The inline style for the element.

CalendarCell#

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

Show props

Name	Type	Description
`date`	`CalendarDate`	The date to render in the cell.
`children`	`ReactNode \| ( (values: CalendarCellRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: CalendarCellRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: CalendarCellRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

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-Calendar {
  /* ... */
}

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

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

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 Calendar are documented below.

Calendar#

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

Name	CSS Selector	Description
`isDisabled`	`[data-disabled]`	Whether the calendar is disabled.
`state`	`—`	State of the calendar.
`isInvalid`	`[data-invalid]`	Whether the calendar is invalid.

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:

Name	CSS Selector	Description
`isHovered`	`[data-hovered]`	Whether the button is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the button is currently in a pressed state.
`isFocused`	`[data-focused]`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`[data-focus-visible]`	Whether the button is keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the button is disabled.

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

<Calendar aria-label="Appointment date">
  <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>
</Calendar>

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

<Calendar aria-label="Appointment date">
  <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>
</Calendar>

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

<Calendar aria-label="Appointment date">
  <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>
</Calendar>

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:

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

Text#

The error message element within a Calendar 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 Calendar, 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).

Component	Context	Props	Ref
`Calendar`	`CalendarContext`	`CalendarProps`	`HTMLDivElement`

This example uses CalendarContext 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 {CalendarContext, useSlottedContext} from 'react-aria-components';

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

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

interface PresetProps {
  date: CalendarDate;
  children: React.ReactNode;
}

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

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

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

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

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

interface PresetProps {
  date: CalendarDate;
  children: React.ReactNode;
}

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

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

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

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

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

interface PresetProps {
  date: CalendarDate;
  children:
    React.ReactNode;
}

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

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

Now you can combine a Calendar and one or more Preset components in a CalendarPicker.

import {startOfWeek, startOfMonth} from '@internationalized/date';
import {useLocale} from 'react-aria';

function Example() {
  let {locale} = useLocale();
  let now = today(getLocalTimeZone());

  return (
    <CalendarPicker>
      <Preset date={now}>Today</Preset>
      <Preset date={startOfWeek(now.add({weeks: 1}), locale)}>Next week</Preset>
      <Preset date={startOfMonth(now.add({months: 1}))}>Next month</Preset>
      <MyCalendar aria-label="Meeting date" />
    </CalendarPicker>
  );
}

import {
  startOfMonth,
  startOfWeek
} from '@internationalized/date';
import {useLocale} from 'react-aria';

function Example() {
  let { locale } = useLocale();
  let now = today(getLocalTimeZone());

  return (
    <CalendarPicker>
      <Preset date={now}>Today</Preset>
      <Preset
        date={startOfWeek(now.add({ weeks: 1 }), locale)}
      >
        Next week
      </Preset>
      <Preset date={startOfMonth(now.add({ months: 1 }))}>
        Next month
      </Preset>
      <MyCalendar aria-label="Meeting date" />
    </CalendarPicker>
  );
}

import {
  startOfMonth,
  startOfWeek
} from '@internationalized/date';
import {useLocale} from 'react-aria';

function Example() {
  let { locale } =
    useLocale();
  let now = today(
    getLocalTimeZone()
  );

  return (
    <CalendarPicker>
      <Preset date={now}>
        Today
      </Preset>
      <Preset
        date={startOfWeek(
          now.add({
            weeks: 1
          }),
          locale
        )}
      >
        Next week
      </Preset>
      <Preset
        date={startOfMonth(
          now.add({
            months: 1
          })
        )}
      >
        Next month
      </Preset>
      <MyCalendar aria-label="Meeting date" />
    </CalendarPicker>
  );
}

Show CSS

.calendar-picker {
  > .react-aria-Button {
    margin: 0 4px 8px 4px;
  }
}

.calendar-picker {
  > .react-aria-Button {
    margin: 0 4px 8px 4px;
  }
}

.calendar-picker {
  > .react-aria-Button {
    margin: 0 4px 8px 4px;
  }
}

Custom children#

Calendar passes props to its child components, such as the heading and buttons, via their associated contexts. These contexts are exported so you can also consume them in your own custom components. This enables you to reuse existing components from your app or component library together with React Aria Components.

Component	Context	Props	Ref
`Heading`	`HeadingContext`	`HeadingProps`	`HTMLHeadingElement`
`Button`	`ButtonContext`	`ButtonProps`	`HTMLButtonElement`
`Text`	`TextContext`	`TextProps`	`HTMLElement`

This example consumes from HeadingContext in an existing styled heading component to make it compatible with React Aria Components. The useContextProps hook merges the local props and ref with the ones provided via context by Calendar.

import type {HeadingProps} from 'react-aria-components';
import {HeadingContext, useContextProps} from 'react-aria-components';

const MyCustomHeading = React.forwardRef(
  (props: HeadingProps, ref: React.ForwardedRef<HTMLHeadingElement>) => {
    // Merge the local props and ref with the ones provided via context.
    [props, ref] = useContextProps(props, ref, HeadingContext);
    // ... your existing Heading component
    return <h2 {...props} ref={ref} />;
  }
);

import type {HeadingProps} from 'react-aria-components';
import {
  HeadingContext,
  useContextProps
} from 'react-aria-components';

const MyCustomHeading = React.forwardRef(
  (
    props: HeadingProps,
    ref: React.ForwardedRef<HTMLHeadingElement>
  ) => {
    // Merge the local props and ref with the ones provided via context.
    [props, ref] = useContextProps(
      props,
      ref,
      HeadingContext
    );
    // ... your existing Heading component
    return <h2 {...props} ref={ref} />;
  }
);

import type {HeadingProps} from 'react-aria-components';
import {
  HeadingContext,
  useContextProps
} from 'react-aria-components';

const MyCustomHeading =
  React.forwardRef(
    (
      props:
        HeadingProps,
      ref:
        React.ForwardedRef<
          HTMLHeadingElement
        >
    ) => {
      // Merge the local props and ref with the ones provided via context.
      [props, ref] =
        useContextProps(
          props,
          ref,
          HeadingContext
        );
      // ... your existing Heading component
      return (
        <h2
          {...props}
          ref={ref}
        />
      );
    }
  );

Now you can use MyCustomHeading within a Calendar, in place of the builtin React Aria Components Heading.

<Calendar>
  <MyCustomHeading />  {/* ... */}
</Calendar>

<Calendar>
  <MyCustomHeading />  {/* ... */}
</Calendar>

<Calendar>
  <MyCustomHeading />  {/* ... */}
</Calendar>

State#

Calendar provides a CalendarState object to its children via CalendarStateContext. This can be used to access and manipulate the calendar's state.

This example shows a CalendarValue component that can be placed within a Calendar to display the currently selected date as a formatted string.

import {CalendarStateContext} from 'react-aria-components';
import {useDateFormatter} from 'react-aria';

function CalendarValue() {
  let state = React.useContext(CalendarStateContext)!;  let date = state.value?.toDate(getLocalTimeZone());
  let formatted = date ? useDateFormatter().format(date) : 'None';
  return <small>Selected date: {formatted}</small>;
}

<Calendar>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    {date => <CalendarCell date={date} />}
  </CalendarGrid>
  <CalendarValue /></Calendar>

import {CalendarStateContext} from 'react-aria-components';
import {useDateFormatter} from 'react-aria';

function CalendarValue() {
  let state = React.useContext(CalendarStateContext)!;  let date = state.value?.toDate(getLocalTimeZone());
  let formatted = date
    ? useDateFormatter().format(date)
    : 'None';
  return <small>Selected date: {formatted}</small>;
}

<Calendar>
  <header>
    <Button slot="previous">◀</Button>
    <Heading />
    <Button slot="next">▶</Button>
  </header>
  <CalendarGrid>
    {(date) => <CalendarCell date={date} />}
  </CalendarGrid>
  <CalendarValue /></Calendar>

import {CalendarStateContext} from 'react-aria-components';
import {useDateFormatter} from 'react-aria';

function CalendarValue() {
  let state = React
    .useContext(
      CalendarStateContext
    )!;  let date = state.value
    ?.toDate(
      getLocalTimeZone()
    );
  let formatted = date
    ? useDateFormatter()
      .format(date)
    : 'None';
  return (
    <small>
      Selected date:{' '}
      {formatted}
    </small>
  );
}

<Calendar>
  <header>
    <Button slot="previous">
      ◀
    </Button>
    <Heading />
    <Button slot="next">
      ▶
    </Button>
  </header>
  <CalendarGrid>
    {(date) => (
      <CalendarCell
        date={date}
      />
    )}
  </CalendarGrid>
  <CalendarValue /></Calendar>

Hooks#

If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See useCalendar for more details.

This example uses the useCalendarGrid hook to build a single week calendar view.

import type {CalendarGridProps} from 'react-aria-components';
import {CalendarStateContext} from 'react-aria-components';
import {useCalendarGrid} from 'react-aria';

function WeekCalendarGrid(props: CalendarGridProps) {
  let state = React.useContext(CalendarStateContext)!;
  let { gridProps } = useCalendarGrid(props, state);

  return (
    <table {...gridProps}>
      <tbody>
        <tr>
          {state.getDatesInWeek(0).map((date, i) => (
            <CalendarCell key={i} date={date} />
          ))}
        </tr>
      </tbody>
    </table>
  );
}

import type {CalendarGridProps} from 'react-aria-components';
import {CalendarStateContext} from 'react-aria-components';
import {useCalendarGrid} from 'react-aria';

function WeekCalendarGrid(props: CalendarGridProps) {
  let state = React.useContext(CalendarStateContext)!;
  let { gridProps } = useCalendarGrid(props, state);

  return (
    <table {...gridProps}>
      <tbody>
        <tr>
          {state.getDatesInWeek(0).map((date, i) => (
            <CalendarCell key={i} date={date} />
          ))}
        </tr>
      </tbody>
    </table>
  );
}

import type {CalendarGridProps} from 'react-aria-components';
import {CalendarStateContext} from 'react-aria-components';
import {useCalendarGrid} from 'react-aria';

function WeekCalendarGrid(
  props:
    CalendarGridProps
) {
  let state = React
    .useContext(
      CalendarStateContext
    )!;
  let { gridProps } =
    useCalendarGrid(
      props,
      state
    );

  return (
    <table
      {...gridProps}
    >
      <tbody>
        <tr>
          {state
            .getDatesInWeek(
              0
            ).map((
              date,
              i
            ) => (
              <CalendarCell
                key={i}
                date={date}
              />
            ))}
        </tr>
      </tbody>
    </table>
  );
}

WeekCalendarGrid can be used within a Calendar in place of the default CalendarGrid component.

<Calendar
  visibleDuration={{ weeks: 1 }}
  defaultValue={today(getLocalTimeZone())}
>
  <div className="week">
    <Heading />
    <Button slot="previous">◀</Button>
    <WeekCalendarGrid />
    <Button slot="next">▶</Button>
  </div>
</Calendar>

<Calendar
  visibleDuration={{ weeks: 1 }}
  defaultValue={today(getLocalTimeZone())}
>
  <div className="week">
    <Heading />
    <Button slot="previous">◀</Button>
    <WeekCalendarGrid />
    <Button slot="next">▶</Button>
  </div>
</Calendar>

<Calendar
  visibleDuration={{
    weeks: 1
  }}
  defaultValue={today(
    getLocalTimeZone()
  )}
>
  <div className="week">
    <Heading />
    <Button slot="previous">
      ◀
    </Button>
    <WeekCalendarGrid />
    <Button slot="next">
      ▶
    </Button>
  </div>
</Calendar>

Show CSS

.week {
  display: grid;
  grid-template-areas:
    "heading heading heading"
    "previous grid next";
  align-items: center;
  justify-items: center;
  gap: 8px;

  .react-aria-Heading {
    grid-area: heading;
    margin: 0;
    font-size: 1.2rem;
  }

  .react-aria-CalendarCell[data-outside-month] {
    display: block;
  }
}

.week {
  display: grid;
  grid-template-areas:
    "heading heading heading"
    "previous grid next";
  align-items: center;
  justify-items: center;
  gap: 8px;

  .react-aria-Heading {
    grid-area: heading;
    margin: 0;
    font-size: 1.2rem;
  }

  .react-aria-CalendarCell[data-outside-month] {
    display: block;
  }
}

.week {
  display: grid;
  grid-template-areas:
    "heading heading heading"
    "previous grid next";
  align-items: center;
  justify-items: center;
  gap: 8px;

  .react-aria-Heading {
    grid-area: heading;
    margin: 0;
    font-size: 1.2rem;
  }

  .react-aria-CalendarCell[data-outside-month] {
    display: block;
  }
}

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.

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.

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 milliseconds.

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.

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.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

'single' | 'visible'

Name	Type	Description
`isDisabled`	`boolean`	Whether the calendar is disabled.
`state`	`CalendarState`	State of the calendar.
`isInvalid`	`boolean`	Whether the calendar is invalid.

Properties

Name	Type	Description
`value`	`CalendarDate \| null`	The currently selected date.
`isDisabled`	`boolean`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	Whether the calendar is in a read only state.
`visibleRange`	`RangeValue<CalendarDate>`	The date range that is currently visible in the calendar.
`timeZone`	`string`	The time zone of the dates currently being displayed.
`isValueInvalid`	`boolean`	Whether the calendar is invalid.
`focusedDate`	`CalendarDate`	The currently focused date.
`isFocused`	`boolean`	Whether focus is currently within the calendar.
`minValue`	`DateValue \| null`	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	The maximum allowed date that a user may select.

Methods

Method	Description
`setValue( (value: CalendarDate \| \| null )): void`	Sets the currently selected date.
`setFocusedDate( (value: CalendarDate )): void`	Sets the focused date.
`focusNextDay(): void`	Moves focus to the next calendar date.
`focusPreviousDay(): void`	Moves focus to the previous calendar date.
`focusNextRow(): void`	Moves focus to the next row of dates, e.g. the next week.
`focusPreviousRow(): void`	Moves focus to the previous row of dates, e.g. the previous work.
`focusNextPage(): void`	Moves focus to the next page of dates, e.g. the next month if one month is visible.
`focusPreviousPage(): void`	Moves focus to the previous page of dates, e.g. the previous month if one month is visible.
`focusSectionStart(): void`	Moves focus to the start of the current section of dates, e.g. the start of the current month.
`focusSectionEnd(): void`	Moves focus to the end of the current section of dates, e.g. the end of the current month month.
`focusNextSection( (larger?: boolean )): void`	Moves focus to the next section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved forward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the next year.
`focusPreviousSection( (larger?: boolean )): void`	Moves focus to the previous section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved backward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the previous year.
`selectFocusedDate(): void`	Selects the currently focused date.
`selectDate( (date: CalendarDate )): void`	Selects the given date.
`setFocused( (value: boolean )): void`	Sets whether focus is currently within the calendar.
`isInvalid( (date: CalendarDate )): boolean`	Returns whether the given date is invalid according to the `minValue` and `maxValue` props.
`isSelected( (date: CalendarDate )): boolean`	Returns whether the given date is currently selected.
`isCellFocused( (date: CalendarDate )): boolean`	Returns whether the given date is currently focused.
`isCellDisabled( (date: CalendarDate )): boolean`	Returns whether the given date is disabled according to the `minValue,`maxValue`, and`isDisabled` props.
`isCellUnavailable( (date: CalendarDate )): boolean`	Returns whether the given date is unavailable according to the `isDateUnavailable` prop.
`isPreviousVisibleRangeInvalid(): boolean`	Returns whether the previous visible date range is allowed to be selected according to the `minValue` prop.
`isNextVisibleRangeInvalid(): boolean`	Returns whether the next visible date range is allowed to be selected according to the `maxValue` prop.
`getDatesInWeek( (weekIndex: number, , startDate?: CalendarDate )): Array<CalendarDate \| null>`	Returns an array of dates in the week index counted from the provided start date, or the first visible date if not given. The returned array always has 7 elements, but may include null if the date does not exist according to the calendar system.

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

'valid' | 'invalid'

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

Name	Type	Description
`isHovered`	`boolean`	Whether the button is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the button is currently in a pressed state.
`isFocused`	`boolean`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`boolean`	Whether the button is keyboard focused.
`isDisabled`	`boolean`	Whether the button is disabled.

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

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

Name	Type	Default	Description
`visibleDuration`	`DateDuration`	`{months: 1}`	The amount of days that will be displayed at once. This affects how pagination works.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	—	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).
`onFocusChange`	`( (date: CalendarDate )) => void`	—	Handler that is called when the focused date changes.
`isInvalid`	`boolean`	—	Whether the current selection is invalid according to application logic.
`pageBehavior`	`PageBehavior`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`value`	`DateValue \| null`	—	The current value (controlled).
`defaultValue`	`DateValue \| null`	—	The default value (uncontrolled).
`onChange`	`( (value: MappedDateValue<DateValue> )) => void`	—	Handler that is called when the value changes.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`children`	`ReactNode \| ( (values: CalendarRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: CalendarRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: CalendarRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

useSlottedContext<T>(
  (context: Context<SlottedContextValue<T>>,
  , slot?: string
    |  | null
)): T
  | null
  | undefined

SlottedValue<T>
  | T
  | null
  | undefined

Name	Type	Description
`slots`	`Record<string \| symbol, T>`

Name	Type	Description
`level`	`number`

Name	Type	Default	Description
`form`	`string`	—	The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document.
`formAction`	`string`	—	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
`formEncType`	`string`	—	Indicates how to encode the form data that is submitted.
`formMethod`	`string`	—	Indicates the HTTP method used to submit the form.
`formNoValidate`	`boolean`	—	Indicates that the form is not to be validated when it is submitted.
`formTarget`	`string`	—	Overrides the target attribute of the button's form owner.
`name`	`string`	—	Submitted as a pair with the button's value as part of the form data.
`value`	`string`	—	The value associated with the button's name when it's submitted with the form data.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`onHoverStart`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	—	Handler that is called when the hover state changes.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`children`	`ReactNode \| ( (values: ButtonRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ButtonRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ButtonRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Name	Type	Description
`elementType`	`string`

useContextProps<T, U extends SlotProps, E extends Element>(
  props: T
    &  & SlotProps,
  ref: ForwardedRef<E>,
  context: Context<ContextValue<U, E>>
): [
  T,
  RefObject<E
    | null>
]

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

SlottedContextValue<WithRef<T, E>>

T & {ref?: ForwardedRef<E>
}

Name	Type	Description
`current`	`T`

Provides the behavior and accessibility implementation for a calendar grid component. A calendar grid displays a single grid of days within a calendar or range calendar which can be keyboard navigated and selected by the user.

useCalendarGrid(
  (props: AriaCalendarGridProps,
  , state: CalendarState
    |  | RangeCalendarState
)): CalendarGridAria

Name	Type	Default	Description
`startDate`	`CalendarDate`	—	The first date displayed in the calendar grid. Defaults to the first visible date in the calendar. Override this to display multiple date grids in a calendar.
`endDate`	`CalendarDate`	—	The last date displayed in the calendar grid. Defaults to the last visible date in the calendar. Override this to display multiple date grids in a calendar.
`weekdayStyle`	`'narrow' \| 'short' \| 'long'`	`"narrow"`	The style of weekday names to display in the calendar grid header, e.g. single letter, abbreviation, or full day name.

Properties

Name	Type	Description
`value`	`RangeValue<DateValue> \| null`	The currently selected date range.
`anchorDate`	`CalendarDate \| null`	The current anchor date that the user clicked on to begin range selection.
`highlightedRange`	`RangeValue<CalendarDate> \| null`	The currently highlighted date range.
`isDragging`	`boolean`	Whether the user is currently dragging over the calendar.
`isDisabled`	`boolean`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	Whether the calendar is in a read only state.
`visibleRange`	`RangeValue<CalendarDate>`	The date range that is currently visible in the calendar.
`timeZone`	`string`	The time zone of the dates currently being displayed.
`isValueInvalid`	`boolean`	Whether the calendar is invalid.
`focusedDate`	`CalendarDate`	The currently focused date.
`isFocused`	`boolean`	Whether focus is currently within the calendar.
`minValue`	`DateValue \| null`	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	The maximum allowed date that a user may select.

Methods

Method	Description
`setValue( (value: RangeValue<DateValue> \| \| null )): void`	Sets the currently selected date range.
`highlightDate( (date: CalendarDate )): void`	Highlights the given date during selection, e.g. by hovering or dragging.
`setAnchorDate( (date: CalendarDate \| \| null )): void`	Sets the anchor date that the user clicked on to begin range selection.
`setDragging( (isDragging: boolean )): void`	Sets whether the user is dragging over the calendar.
`setFocusedDate( (value: CalendarDate )): void`	Sets the focused date.
`focusNextDay(): void`	Moves focus to the next calendar date.
`focusPreviousDay(): void`	Moves focus to the previous calendar date.
`focusNextRow(): void`	Moves focus to the next row of dates, e.g. the next week.
`focusPreviousRow(): void`	Moves focus to the previous row of dates, e.g. the previous work.
`focusNextPage(): void`	Moves focus to the next page of dates, e.g. the next month if one month is visible.
`focusPreviousPage(): void`	Moves focus to the previous page of dates, e.g. the previous month if one month is visible.
`focusSectionStart(): void`	Moves focus to the start of the current section of dates, e.g. the start of the current month.
`focusSectionEnd(): void`	Moves focus to the end of the current section of dates, e.g. the end of the current month month.
`focusNextSection( (larger?: boolean )): void`	Moves focus to the next section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved forward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the next year.
`focusPreviousSection( (larger?: boolean )): void`	Moves focus to the previous section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved backward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the previous year.
`selectFocusedDate(): void`	Selects the currently focused date.
`selectDate( (date: CalendarDate )): void`	Selects the given date.
`setFocused( (value: boolean )): void`	Sets whether focus is currently within the calendar.
`isInvalid( (date: CalendarDate )): boolean`	Returns whether the given date is invalid according to the `minValue` and `maxValue` props.
`isSelected( (date: CalendarDate )): boolean`	Returns whether the given date is currently selected.
`isCellFocused( (date: CalendarDate )): boolean`	Returns whether the given date is currently focused.
`isCellDisabled( (date: CalendarDate )): boolean`	Returns whether the given date is disabled according to the `minValue,`maxValue`, and`isDisabled` props.
`isCellUnavailable( (date: CalendarDate )): boolean`	Returns whether the given date is unavailable according to the `isDateUnavailable` prop.
`isPreviousVisibleRangeInvalid(): boolean`	Returns whether the previous visible date range is allowed to be selected according to the `minValue` prop.
`isNextVisibleRangeInvalid(): boolean`	Returns whether the next visible date range is allowed to be selected according to the `maxValue` prop.
`getDatesInWeek( (weekIndex: number, , startDate?: CalendarDate )): Array<CalendarDate \| null>`	Returns an array of dates in the week index counted from the provided start date, or the first visible date if not given. The returned array always has 7 elements, but may include null if the date does not exist according to the calendar system.

Name	Type	Description
`gridProps`	`DOMAttributes`	Props for the date grid element (e.g. `<table>`).
`headerProps`	`DOMAttributes`	Props for the grid header element (e.g. `<thead>`).
`weekDays`	`string[]`	A list of week day abbreviations formatted for the current locale, typically used in column headers.

All DOM attributes supported across both HTML and SVG elements.

Extends: AriaAttributes, ReactDOMAttributes

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`