> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Calendar Component

## Article: Calendar Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/calendar/calendar-component.md

## Article Content:

# Calendar

_Components/Form/Calendar/Calendar_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/calendar>

## Overview

```jsx
() => {
  const [value, setValue] = React.useState(null);
  return (
    <StorybookComponents.Stack>
      <Calendar
        value={value}
        onChange={setValue}
        dateIndication={({ date, isSelected }) => {
          if (date.getTime() < new Date().getTime()) {
            return (
              <Box align="center">
                <Box
                  width="4px"
                  height="4px"
                  borderRadius="50%"
                  backgroundColor={isSelected ? 'D60' : 'B20'}
                />
              </Box>
            );
          }
        }}
      />
    </StorybookComponents.Stack>
  );
};
```

Calendar component lets to pick a date while seeing the full month of days. It's used in `<DatePicker/>` component, but it can be used alone too.

### Do

- Use it to show the list of available days to choose from
- Use it if calendar needs to be prominent all the time
- Use it to display multiple months at once

### Don't

- Don't use it when user needs to enter a lot of data at once. Use `<DatePicker/>` instead.
- Don't use it when screen space is limited. Use `<DatePicker/>` instead.

### Feature examples

#### Layout

Change calendar's layout using \`numOfMonths\` prop. It can display 1 or 2 months.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  return (
    <StorybookComponents.Stack flexDirection="column">
      <Calendar
        value={value}
        onChange={setValue}
        numOfMonths={1}
        autoFocus={false}
      />
      <Calendar
        value={value}
        onChange={setValue}
        numOfMonths={2}
        autoFocus={false}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Size

Adjust the component \`size\` using size prop. It supports 2 sizes:\
 - \`medium\` (default) - use it in all common cases.\
 - \`small\` - use it in dense layouts like Bookings Calendar to save vertical and horizontal space.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  return (
    <StorybookComponents.Stack>
      <Calendar
        value={value}
        onChange={setValue}
        size="medium"
        autoFocus={false}
      />
      <Calendar
        value={value}
        onChange={setValue}
        size="small"
        autoFocus={false}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Date Indication

Mark important dates with \`dateIndication\` prop. It's helpful when the calendar needs to highlight the dates with happening events.

```jsx
() => {
  const [value, setValue] = React.useState(new Date());
  return (
    <Calendar
      value={value}
      onChange={setValue}
      autoFocus={false}
      dateIndication={({ date, isSelected }) => {
        if (date.getTime() < new Date().getTime()) {
          return (
            <Box align="center">
              <Box
                width="4px"
                height="4px"
                borderRadius="50%"
                backgroundColor={isSelected ? 'D60' : 'B20'}
              />
            </Box>
          );
        }
      }}
    />
  );
};
```

#### Selection Mode

Enable select the range of dates with \`selectionMode\` prop. It supports 2 values:\
 - \`day\` (default) - lets to select 1 day.\
 - \`range\` - lets to select any range of dates.

```jsx
() => {
  const date = new Date();
  const [day, setDay] = React.useState(date);
  const [range, setRange] = React.useState({
    from: new Date(),
    to: new Date(date.setMonth(date.getMonth() + 1)),
  });

  return (
    <StorybookComponents.Stack>
      <Calendar
        selectionMode="day"
        value={day}
        onChange={setDay}
        autoFocus={false}
      />
      <Calendar
        selectionMode="range"
        value={range}
        onChange={setRange}
        autoFocus={false}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Excluding Dates

Control what dates the user can select with 2 props:\
 - \`filterDate\` - define what dates will be selectable.\
 - \`excludePastDates\` - allow selecting only today and future dates.

```jsx
() => {
  const [calendar1Value, setCalendar1Value] = React.useState(new Date());
  const [calendar2Value, setCalendar2Value] = React.useState(new Date());

  const filterDate = (date) => date.getTime() < new Date();

  return (
    <StorybookComponents.Stack>
      <Calendar
        value={calendar1Value}
        onChange={setCalendar1Value}
        filterDate={filterDate}
        autoFocus={false}
      />
      <Calendar
        value={calendar2Value}
        onChange={setCalendar2Value}
        excludePastDates
        autoFocus={false}
      />
    </StorybookComponents.Stack>
  );
};
```

#### Select  Month and Year

Let the user quickly change the month and year values with props::\
 - \`showMonthDropdown \` - enables month dropdown.\
 - \`showYearDropdown\` - enables year dropdown.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  return (
    <Calendar
      value={value}
      onChange={setValue}
      showMonthDropdown
      showYearDropdown
      autoFocus={false}
    />
  );
};
```

#### Localization

Change the language using \`locale\` prop. Some languages will change the start of the week day and order of month and year. First Day of the week can be controlled manually with \`firstDayOfWeek\` prop.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  return (
    <Calendar
      value={value}
      onChange={setValue}
      locale="ko"
      firstDayOfWeek={0}
      autoFocus={false}
    />
  );
};
```

### Common use case examples

#### Event scheduling

Use a calendar with time picker to let our users set the appointment date or article publish date.

```jsx
() => {
  const [value, setValue] = React.useState(new Date());
  const [time, setTime] = React.useState('10.00');
  const timeslots = [
    '10.00',
    '10.20',
    '10.40',
    '11.00',
    '11.20',
    '11.40',
    '12.00',
    '12.20',
    '12.40',
  ];

  const onTimeInputChange = () => setTime('');

  return (
    <CustomModalLayout
      primaryButtonText="Schedule"
      secondaryButtonText="Cancel"
      onCloseButtonClick={() => {}}
      title="Schedule Post"
      subtitle="When do you want to publish or post?"
      showHeaderDivider
      showFooterDivider
      removeContentPadding
    >
      <Layout gap="0">
        <Cell span={5}>
          <Calendar
            value={value}
            onChange={setValue}
            excludePastDates
            autoFocus={false}
          />
        </Cell>
        <Cell span={7}>
          <Box maxHeight="400px">
            <Divider direction="vertical" />
            <Box direction="vertical" width="100%">
              <Box margin="SP3">
                <FormField label="Time">
                  <TimeInput onChange={onTimeInputChange} />
                </FormField>
              </Box>
              <Box overflow="scroll" direction="vertical">
                {timeslots.map((slot) => (
                  <ListItemSelect
                    prefix={
                      <Box>
                        <Icons.Time />
                      </Box>
                    }
                    onClick={() => setTime(slot)}
                    selected={slot === time}
                    title={slot}
                  />
                ))}
              </Box>
            </Box>
          </Box>
        </Cell>
      </Layout>
    </CustomModalLayout>
  );
};
```

## Code

```jsx
import { Calendar } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` *(required)* | `boolean` | `true` | Focus selected day automatically when component mounts or updates. |
| `containFocus` | `boolean` | — | Specifies whether focus is trapped in the calendar while `autoFocus` is enabled, and returned to the previously focused element when the calendar unmounts. |
| `dataHook` | `string` | — | Applies as data-hook HTML attribute that can be used in the tests. |
| `dateIndication` *(required)* | `FC<dateIndicationProps>` | — | ##### Add an indication under a specific date. Function returns the indication node of a specific date or null if this day doesn't have an indication. - `param` {date: Date, isSelected: boolean } - `date` - a date - `isSelected` - whether this date is the selected date - `return` {React.node} - the indication node of a specific date or null if this day doesn't have an indication. |
| `excludePastDates` *(required)* | `boolean` | `false` | Specify whether past dates should be selectable or not. |
| `filterDate` *(required)* | `(date: Date) => boolean` | — | ##### Specify selectable dates: * `param` {Date} `date` - a date to check * `return` {boolean} - true if `date` should be selectable, false otherwise |
| `firstDayOfWeek` | `0 \| 1 \| 5 \| 2 \| 3 \| 4 \| 6` | — | First day of the week, allowing only from 0 to 6 (Sunday to Saturday). The default value is 1 which means Monday. |
| `leftArrowAriaLabel` | `string` | — | Defines a string value that labels the left arrow in calendar header. |
| `leftArrowAriaLabelledBy` | `string` | — | Identifies the element that labels the left arrow in calendar header. |
| `locale` | `"th" \| "tr" \| "id" \| "fr" \| "no" \| "en" \| "en-US" \| "en-GB" \| "en-AU" \| "en-CA" \| "ar" \| "bg" \| "ca" \| "zh" \| "zh-TW" \| "zh-HK" \| "zh-MO" \| "cs" \| "da" \| "nl" \| "fi" \| "fr-CA" \| "fr-CH" \| "fr-BE" \| "de" \| "de-CH" \| "de-AT" \| "el" \| "he" \| "hi" \| "hu" \| "it" \| "ja" \| "ko" \| "lt" \| "ms" \| "nb" \| "nn" \| "pl" \| "pt-BR" \| "pt" \| "ro" \| "ru" \| "sk" \| "sl" \| "es" \| "es-419" \| "es-AR" \| "es-MX" \| "es-US" \| "sv" \| "tl" \| "uk" \| "vi"` | — | Specify date picker instance locale. |
| `monthDropdownAriaLabel` | `string` | — | Defines a string value that labels the months dropdown in calendar header. |
| `monthDropdownAriaLabelledBy` | `string` | — | Identifies the element that labels the months dropdown in calendar header. |
| `numOfMonths` *(required)* | `1 \| 2` | `1` | Allows to display multiple months at once. Currently it shows 1 or 2 months only. |
| `onChange` *(required)* | `(date: Date) => void` | — | Provides a callback function when day in selected in the calendar. |
| `onClose` *(required)* | `() => void` | — | Defines a callback function that is  called whenever a user presses escape, clicks outside of the element or a date is selected and `shouldCloseOnSelect` is set. Receives an event as a first argument. |
| `onKeyDown` | `(event: KeyboardEvent<Element>) => void` | — | Provides a callback function when any key is clicked in the calendar. |
| `onMonthChange` | `(monthStart: Date) => void` | — | Defines a callback function that is called with the date of the first day of the month whenever the user selects a month in the calendar. |
| `rightArrowAriaLabel` | `string` | — | Defines a string value that labels the right arrow in calendar header. |
| `rightArrowAriaLabelledBy` | `string` | — | Identifies the element that labels the right arrow in calendar header. |
| `rtl` | `boolean` | — | Specify whether RTL mode is enabled or not. When true, the keyboard navigation is changed, meaning pressing the right arrow navigates to the previous day, and pressing the left arrow navigates to the next day. |
| `selectionMode` *(required)* | `"day" \| "range"` | `'day'` | Whether the user should be able to select a date range, or just a single day. |
| `shouldCloseOnSelect` *(required)* | `boolean` | `true` | Specify whether the calendar closes on day selection. |
| `showMonthDropdown` *(required)* | `boolean` | `false` | Displays a selectable monthDropdown. |
| `showYearDropdown` *(required)* | `boolean` | `false` | Displays a selectable yearDropdown. |
| `size` *(required)* | `"small" \| "medium"` | `'medium'` | Defines calendar size property. It can be either small or medium (default) |
| `today` | `Date` | — | Sets today's date. The today indication is added automatically according to the user timezone but in some cases, we need the ability to add the today indication based on the business timezone. |
| `value` | `Date \| { from?: string \| Date \| undefined; to?: string \| Date \| undefined; }` | — | Defines the selected date. |
| `yearDropdownAriaLabel` | `string` | — | Defines a string value that labels the years dropdown in calendar header. |
| `yearDropdownAriaLabelledBy` | `string` | — | Identifies the element that labels the years dropdown in calendar header. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { CalendarUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { CalendarTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { CalendarTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { CalendarTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `close` | — |
| `getCurrentMonthWithYear` | — |
| `getNthWeekDayName` | — |
| `clickOnNthDay` | — |
| `clickDay` | — |
| `isDayActive` | — |
| `clickOnNthDayOfTheMonth` | — |
| `clickOnSelectedDay` | — |
| `clickOnYearDropdown` | — |
| `clickOnMonthDropdown` | — |
| `clickOnNthYear` | — |
| `clickOnPrevMonthButton` | — |
| `clickOnNextMonthButton` | — |
| `keyboardNextYear` | — |
| `keyboardPrevYear` | — |
| `isHeaderExists` | — |
| `isYearDropdownExists` | — |
| `isYearCaptionExists` | — |
| `isMonthDropdownExists` | — |
| `isMonthCaptionExists` | — |
| `getMonthCaption` | — |
| `getMonthDropdownLabel` | — |
| `getSelectedYear` | — |
| `getFocusedDay` | Returns the text of the focused day or `null` if there is no focused day |
| `getFocusedDayElement` | — |
| `pressLeftArrow` | — |
| `pressRightArrow` | — |
| `getSelectedDay` | — |
| `triggerKeyDown` | — |
| `isFocusedDayVisuallyUnfocused` | — |
| `containsVisuallyUnfocusedDay` | — |
| `isTwoMonthsLayout` | — |
| `getMonthDropdownDriver` | — |
| `getYearDropdownDriver` | — |
| `getNumOfVisibleMonths` | — |
| `getNumOfSelectedDays` | — |
| `getSelectedDays` | TODO: return `Promise<Date[]>` in the next major release (see docs/major-release.md) |
| `getSize` | Returns size property value currently set on component |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.344.0** (2026-10-28) — maintenance release, no component-specific changes
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.336.0** (2026-10-13) — maintenance release, no component-specific changes
- **1.335.0** (2026-10-12) — breaking: in Studio 2.0 and Studio 2.0 Light the day grid follows Harmony's layout — a 2px gap between days, weekday labels and weeks, 8px rounded range days and start/end tiles without the half-band connector, today as a plain filled tile without the 3px inner ring, and 18px (medium) / 12px (small) padding. In Studio 2.0 the selected range is now visible: its days are now clearly distinct from the surface instead of matching it. Other colors stay as they were. ([#17386](invalid-url)) — has visual changes
- **1.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.324.0** (2026-09-14) — breaking: in Harmony (odeditor) today's date is filled edge to edge, without the inset ring that shrinks it in other themes. ([#17058](invalid-url)) — has visual changes
- **1.324.0** (2026-09-14) — fix: in Harmony (odeditor) the selected day and range edges are now dark instead of blue, hovered and in-range days use a light grey fill, today is marked with a grey fill, and weekday names are muted grey. Also in Harmony, days are separated by small gaps with tighter grid padding, and every day of a selected range is an individually rounded square instead of a continuous bar. ([#17048](invalid-url)) — has visual changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.316.0** (2026-08-25) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.243.0** (2025-12-23) — fix: flaky issues appearing ([#15706](invalid-url))
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.239.0** (2025-12-12) — maintenance release, no component-specific changes
- **1.225.0** (2025-11-07) — maintenance release, no component-specific changes
- **1.220.0** (2025-09-29) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.209.0** (2025-07-30) — maintenance release, no component-specific changes
- **1.191.1** (2025-05-27) — fix: fix dropdown accessibility ([#14867](invalid-url))
- **1.189.0** (2025-05-15) — maintenance release, no component-specific changes
- **1.188.1** (2025-05-14) — maintenance release, no component-specific changes
- **1.187.0** (2025-05-07) — maintenance release, no component-specific changes
- **1.184.0** (2025-04-30) — fix: flaky semantic class tests ([#14813](invalid-url))
- **1.183.0** (2025-04-24) — maintenance release, no component-specific changes
- **1.182.0** (2025-04-23) — maintenance release, no component-specific changes
- **1.181.0** (2025-04-18) — maintenance release, no component-specific changes
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.149.0** (2024-12-19) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.112.0** (2024-07-03) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.100.2** (2024-04-05) — fix: icon size & disabled days color ([#13576](invalid-url))
- **1.98.0** (2024-03-15) — fix: arrows style ([#13438](invalid-url))
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes