---
title: Calendar
description: A component that allows users to select a single date.
thumbnail:
  image: /previews/components/core/calendar.jpeg
  video: /previews/components/core/calendar.mp4
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Calendar.html
  - label: Aria API Reference
    href: https://react-spectrum.adobe.com/react-aria/Calendar.html#props
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/dates/calendar.mdx?plain=1
---

<ComponentPreview name="core/calendar-default" preview={`<Calendar />`} />

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add calendar
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/calendar" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

Use `Calendar` to allow users to select a single date.

## Options

### Label

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.

<ComponentPreview
  name="core/calendar-label"
  preview={`<Calendar aria-label="Event date" />`}
/>

### Error message

`Calendar` tries to avoid allowing the user to select invalid dates in the first place (see [Min and max values](#min-and-max-values) and [Unavailable dates](#unavailable-dates)). However, if according to application logic a selected date is invalid, Use `isInvalid` and `errorMessage` props.

<ComponentPreview
  name="core/calendar-error-message"
  preview={`const [date, setDate] = React.useState(today(getLocalTimeZone()));
  const { locale } = useLocale();
  const isInvalid = isWeekend(date, locale);
  return (
    <Calendar
      value={date}
      onChange={setDate}
      isInvalid={isInvalid}
      errorMessage={"We are closed on weekends"}
    />
  );`}
/>

### Min and max values

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.

<ComponentPreview
  name="core/calendar-validation"
  preview={`<Calendar minValue={today(getLocalTimeZone())} />`}
/>

### Unavailable dates

`Calendar` supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.

{/* prettier-ignore-start */}

<ComponentPreview 
  name="core/calendar-unvailable-dates" 
  preview={`const now = today(getLocalTimeZone());
  const disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })],
  ];

  const { locale } = useLocale();
  const isDateUnavailable = (date: DateValue) =>
    isWeekend(date, locale) ||
    disabledRanges.some(
      (interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
    );

  return (
    <Calendar
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
    />
);`}
/>

{/* prettier-ignore-end */}

### Visible months

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

<ComponentPreview
  name="core/calendar-visible-months"
  preview={`<Calendar visibleMonths={2} />`}
/>

### Page behaviour

The `pageBehavior` prop allows you to control how the calendar navigates between months.

<ComponentPreview
  name="core/calendar-page-behaviour"
  preview={`<Calendar visibleMonths={2} pageBehavior="single" />`}
/>

### Disabled

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

<ComponentPreview
  name="core/calendar-disabled"
  preview={`<Calendar isDisabled />`}
/>

### Read only

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

<ComponentPreview
  name="core/calendar-read-only"
  preview={`<Calendar isReadOnly value={today(getLocalTimeZone())} />`}
/>

## Uncontrolled

An initial, uncontrolled value can be provided to the `Calendar` using the `defaultValue` prop.

<ComponentPreview
  name="core/calendar-uncontrolled"
  preview={`<Calendar defaultValue={today(getLocalTimeZone())} />`}
/>

## Controlled

The `Calendar` component can be controlled by passing the `value` and `onChange` props.

<ComponentPreview
  name="core/calendar-controlled"
  preview={`const [value, setValue] = React.useState(today(getLocalTimeZone()));
return <Calendar aria-label="Date (controlled)" value={value} onChange={setValue} />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview name="core/calendar-composition" />

## API Reference

| Prop                  | Type                                                                                                  | Default     | Description                                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibleMonths`       | `number`                                                                                              | `1`         | The number of months to display at once. Up to 3 months are supported.                                                                              |
| `minValue`            | `DateValue`                                                                                           | -           | The minimum allowed date that a user may select.                                                                                                    |
| `maxValue`            | `DateValue`                                                                                           | -           | The maximum allowed date that a user may select.                                                                                                    |
| `isDateUnavailable`   | `(date: DateValue) => boolean`                                                                        | -           | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.                                            |
| `isDisabled`          | `boolean`                                                                                             | `false`     | Whether the calendar is disabled.                                                                                                                   |
| `isReadOnly`          | `boolean`                                                                                             | `false`     | Whether the calendar value is immutable.                                                                                                            |
| `autoFocus`           | `boolean`                                                                                             | `false`     | Whether to automatically focus the calendar when it mounts.                                                                                         |
| `focusedValue`        | `DateValue`                                                                                           | -           | Controls the currently focused date within the calendar.                                                                                            |
| `defaultFocusedValue` | `DateValue`                                                                                           | -           | The date that is focused when the calendar first mounts (uncountrolled).                                                                            |
| `isInvalid`           | `boolean`                                                                                             | -           | Whether the current selection is invalid according to application logic.                                                                            |
| `pageBehavior`        | `'single' \| 'visible'`                                                                               | `'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`                                                                                              | -           | The CSS className for the element.                                                                                                                  |
| `style`               | `CSSProperties \| (values: CalendarRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -           | The inline style for the element. A function may be provided to compute the style based on component state.                                         |

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

## Accessibility

### Keyboard interactions

| Key             | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `Tab`           | Moves focus to the next focusable item in the calendar.       |
| `Shift+Tab`     | Moves focus to the previous focusable item in the calendar.   |
| `ArrowRight`    | Moves focus to the next day.                                  |
| `ArrowLeft`     | Moves focus to the previous day.                              |
| `ArrowDown`     | Moves focus to the same day of the week in the next week.     |
| `ArrowUp`       | Moves focus to the same day of the week in the previous week. |
| `Space` `Enter` | Selects the focused date.                                     |
