> 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: CalendarPanel Component

## Article: CalendarPanel Component

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

## Article Content:

# CalendarPanel

_Components/Form/Calendar/CalendarPanel_

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

## Overview

```jsx
() => {
  const [selectedValue, setSelectedValue] = React.useState(new Date());

  const today = new Date();
  const getDateDaysAgo = (days) =>
    new Date(Date.now() - days * 1000 * 60 * 60 * 24);

  const presets = [
    {
      id: 0,
      selectedDays: getDateDaysAgo(1),
      value: 'Yesterday',
    },
    {
      id: 1,
      selectedDays: today,
      value: 'Today',
    },
    {
      id: 2,
      selectedDays: {
        from: getDateDaysAgo(7),
        to: today,
      },
      value: 'Last 7 Days',
    },
    {
      id: 3,
      selectedDays: {
        from: getDateDaysAgo(30),
        to: today,
      },
      value: 'Last 30 Days',
    },
    {
      id: 4,
      selectedDays: {
        from: getDateDaysAgo(90),
        to: today,
      },
      value: 'Last 90 Days',
    },
  ];

  return (
    <CalendarPanel
      presets={presets}
      onChange={(value) => setSelectedValue(value)}
      value={selectedValue}
      footer={() => (
        <CalendarPanelFooter
          primaryActionLabel="Submit"
          secondaryActionLabel="Cancel"
          primaryActionDisabled={false}
          primaryActionOnClick={() => {}}
          secondaryActionOnClick={() => {}}
          selectedDays={selectedValue}
          dateToString={(date) => date.toLocaleDateString('en-US')}
        />
      )}
    />
  );
};
```

Calendar Panel component lets a user pick a date while providing a great overview of available selections.It's built using `<Calendar/>` and `<CalendarPanelFooter/>` components.

### Do

- Use it when a wider view of available dates should be seen
- Use it when needed to select recurring range of days, for example in charts
- Use it when extra validation is needed before submitting the date selection

### Don't

- Don't use it in compact layouts, use `<Calendar/>` instead
- Don't use it in forms, use `<DatePicker/>` instead

### Feature examples

#### Presets

Empower the user to quickly select a predefined range or date using \`presets\` prop.

```jsx
() => {
  const [selectedValue, setSelectedValue] = React.useState(undefined);

  const today = new Date();
  const getDateDaysAgo = (days) =>
    new Date(Date.now() - days * 1000 * 60 * 60 * 24);

  const presets = [
    {
      id: 0,
      selectedDays: getDateDaysAgo(1),
      value: 'Yesterday',
    },
    {
      id: 1,
      selectedDays: today,
      value: 'Today',
    },
    {
      id: 2,
      selectedDays: {
        from: getDateDaysAgo(7),
        to: today,
      },
      value: 'Last 7 Days',
    },
    {
      id: 3,
      selectedDays: {
        from: getDateDaysAgo(30),
        to: today,
      },
      value: 'Last 30 Days',
    },
    {
      id: 4,
      selectedDays: {
        from: getDateDaysAgo(90),
        to: today,
      },
      value: 'Last 90 Days',
    },
  ];

  return (
    <CalendarPanel
      presets={presets}
      onChange={(value) => setSelectedValue(value)}
      value={selectedValue}
      autoFocus={false}
    />
  );
};
```

#### Footer

Make the date selection secure by using \`footer\` prop which adds summarized date selection and confirmation actions.

```jsx
<CalendarPanel
  value={new Date()}
  footer={({ selectedDays }) => (
    <CalendarPanelFooter
      primaryActionLabel="Submit"
      secondaryActionLabel="Cancel"
      primaryActionDisabled={false}
      primaryActionOnClick={() => {}}
      secondaryActionOnClick={() => {}}
      selectedDays={selectedDays}
      dateToString={(date) => date.toLocaleDateString('en-US')}
    />
  )}
  autoFocus={false}
/>;
```

#### Number of Months

Specify a number of months visible inside of a panel with \`numOfMonths\` prop.\
\
By default panel displays 2 months at once. Display a single month only when presets are available.

```jsx
() => {
  const presets = [
    {
      id: 0,
      value: 'Last 7 Days',
    },
    {
      id: 1,
      value: 'Last Month',
    },
    {
      id: 2,
      value: 'Next 2 days',
    },
    {
      id: 3,
      value: 'Next 3 days',
    },
    {
      id: 4,
      value: 'Next 5 days',
    },
  ];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <StorybookComponents.Stack>
        <CalendarPanel numOfMonths={1} presets={presets} autoFocus={false} />
      </StorybookComponents.Stack>
      <StorybookComponents.Stack>
        <CalendarPanel numOfMonths={2} presets={presets} autoFocus={false} />
      </StorybookComponents.Stack>
    </StorybookComponents.Stack>
  );
};
```

#### Selection Mode

Enable users to 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 [day, setDay] = React.useState(new Date());
  const [range, setRange] = React.useState({ from: new Date() });

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

#### Month and Year Selection

Let the user quickly change the month and year values with:\
 - \`showMonthDropdown\` (default) - enables month selection dropdown.\
 - \`showYearDropdown\` - enables year selection dropdown.

```jsx
<CalendarPanel showMonthDropdown showYearDropdown autoFocus={false} />;
```

#### Excluding Dates

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <CalendarPanel filterDate={(date) => date < new Date()} autoFocus={false} />
  <CalendarPanel excludePastDates autoFocus={false} />
</StorybookComponents.Stack>;
```

#### 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.\
\
Presets and footer actions aren't controlled by this and have to be translated manually.\
\
When using \`Yoshi 5\` with \`BM Flow\` there's no need to use \`locale\` prop anymore. It is handled automatically.

```jsx
<CalendarPanel
  locale="ko"
  presets={[{ value: "I'm still English" }]}
  footer={() => (
    <CalendarPanelFooter
      secondaryActionLabel="Me too"
      primaryActionLabel="Me as well"
      primaryActionDisabled={false}
      primaryActionOnClick={() => {}}
      secondaryActionOnClick={() => {}}
      selectedDays={new Date()}
      dateToString={(date) => date.toLocaleDateString('en-US')}
    />
  )}
  autoFocus={false}
/>;
```

### Common use case examples

#### Trigger

Call it out from any action component such as `<IconButton/>`, `<TextButton/>`, `<Button/>`, etc. Use it to filter data and content.

```jsx
() => {
  const today = new Date();
  const dayInMilliseconds = 1000 * 60 * 60 * 24;
  const getDateDaysAgo = (days) =>
    new Date(Date.now() - days * dayInMilliseconds);
  const getShortDate = (date) => date.toLocaleDateString();
  const oneDayChartData = [
    {
      value: Math.floor(Math.random() * 1000),
      label: '00:00',
    },
    {
      value: Math.floor(Math.random() * 1000),
      label: '23:59',
    },
  ];

  const [currentRange, setCurrentRange] = React.useState({
    from: today,
    to: today,
  });

  const [analyticsData, setAnalyticsData] = React.useState({
    chartData: oneDayChartData,
    range: { from: today, to: today },
    rangeText: getShortDate(today),
  });
  const [panelShown, setPanelShown] = React.useState(false);

  const presets = [
    {
      id: 0,
      selectedDays: {
        from: getDateDaysAgo(7),
        to: today,
      },
      value: 'Last 7 Days',
    },
    {
      id: 1,
      selectedDays: {
        from: getDateDaysAgo(30),
        to: today,
      },
      value: 'Last 30 Days',
    },
    {
      id: 2,
      selectedDays: {
        from: getDateDaysAgo(90),
        to: today,
      },
      value: 'Last 90 Days',
    },
  ];

  const getRangeOfDates = (startDate, endDate) => {
    const diffInDays = Math.ceil(
      (endDate.getTime() - startDate.getTime()) / dayInMilliseconds + 1,
    );
    return new Array(diffInDays)
      .fill(0)
      .map(
        (_, index) => new Date(startDate.getTime() + index * dayInMilliseconds),
      );
  };

  const getChartAreaData = (startDate, endDate) => {
    if (startDate.getTime() === endDate.getTime()) {
      return oneDayChartData;
    }

    return getRangeOfDates(startDate, endDate).map((date, index) => ({
      label: `${date.getMonth() + 1}/${date.getDate()}`,
      value: Math.floor(Math.random() * 1000),
    }));
  };

  const getRangeText = (startDate, endDate) =>
    startDate.getTime() === endDate.getTime()
      ? getShortDate(startDate)
      : `${getShortDate(startDate)}-${getShortDate(endDate)}`;

  const onSubmitClick = () => {
    setPanelShown(false);
    setAnalyticsData({
      range: currentRange,
      chartData: getChartAreaData(currentRange.from, currentRange.to),
      rangeText: getRangeText(currentRange.from, currentRange.to),
    });
  };

  const onCancelClick = () => {
    setPanelShown(false);
    setCurrentRange(analyticsData.range);
  };

  return (
    <Card>
      <Card.Header
        title="Analytics"
        suffix={
          <Popover
            shown={panelShown}
            onClickOutside={onCancelClick}
            appendTo="window"
            placement="bottom"
          >
            <Popover.Element>
              <TextButton onClick={() => setPanelShown(!panelShown)}>
                <Box verticalAlign="middle">
                  {analyticsData.rangeText}
                  <Icons.ChevronDownSmall />
                </Box>
              </TextButton>
            </Popover.Element>

            <Popover.Content>
              <CalendarPanel
                presets={presets}
                value={currentRange}
                onChange={setCurrentRange}
                selectionMode="range"
                footer={({ selectedDays }) => (
                  <CalendarPanelFooter
                    primaryActionLabel="Submit"
                    secondaryActionLabel="Cancel"
                    primaryActionDisabled={false}
                    primaryActionOnClick={onSubmitClick}
                    secondaryActionOnClick={onCancelClick}
                    selectedDays={selectedDays}
                    dateToString={(date) => date.toLocaleDateString('en-US')}
                  />
                )}
                autoFocus={false}
              />
            </Popover.Content>
          </Popover>
        }
      />
      <Card.Divider />
      <Card.Content>
        <AreaChart data={analyticsData.chartData} />
      </Card.Content>
    </Card>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` | `true` | Focuses the selected day automatically when the component mounts or updates. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `excludePastDates` | `boolean` | — | Specifies whether past dates should be selectable or not. |
| `filterDate` | `(date: Date) => boolean` | — | Specifies dates that are selectable. Only the dates that match defined criteria are available for a user to select. |
| `footer` | `(selectedDays: SelectedDaysType, submitDisabled: boolean) => void` | — | Renders a panel footer. Pass `<CalendarPanelFooter/>` in all common cases. `({selectedDays, submitDisabled}) => void` - `selectedDays` is the same as the CalendarPanel's `value` prop. `submitDisabled` is true when the current selectedDays isn't valid for submission. |
| `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" \| DateFnsLocale` | — | Specifies date picker instance locale. |
| `numOfMonths` | `number` | `2` | Defines a number of months to display inside of a panel. |
| `onChange` | `(selectedDays: SelectedDaysType) => void` | — | Defines a callback function  which is called whenever the user selects a day or a date range in the calendar. |
| `onClose` | `(e: SyntheticEvent<Element, Event>) => void` | — | Defines a callback function which is called whenever user press `escape` or click outside of the element. |
| `presets` | `PresetType[] \| { selectedDays?: SelectedDaysType \| undefined; id?: string \| number \| undefined; }` | — | Defines an array of predefined calendar presets that are displayed as select items on the left side of a panel. |
| `ref` | `null \| string \| (instance: CalendarPanelImperativeActions \| null) => void \| RefObject<CalendarPanelImperativeActions>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `selectionMode` | `"day" \| "range"` | — | Specifies if user can select a single day or a date range. |
| `shouldCloseOnSelect` | `boolean` | — | Specifies whether calendar should close on a day selection. |
| `showMonthDropdown` | `boolean` | — | Specifies whether to display a month selection dropdown inside of a calendar. |
| `showYearDropdown` | `boolean` | — | Specifies whether to display a year selection dropdown inside of a calendar. |
| `value` | `string \| Date \| DateRangeType` | — | Defines a selected date or date range. |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `calendarDriver` | — |
| `presetsDropdownLayoutDriver` | — |
| `isDropdownExists` | — |
| `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.330.3** (2026-09-29) — 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: the footer actions use the dark button skin and the footer and presets list get tighter padding in every theme, and in Harmony (odeditor) the dividers next to the presets list and above the footer no longer render. ([#17058](invalid-url)) — has visual 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.288.0** (2026-06-15) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — 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.250.0** (2026-01-27) — maintenance release, no component-specific changes
- **1.239.0** (2025-12-12) — 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.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.105.1** (2024-05-22) — fix: fix constant import path ([#13757](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes