CalendarPanel

Components/Form/Calendar/CalendarPanel

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

Overview

Copy

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.

Copy

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

Copy

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.

Copy

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.

Copy

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.

Copy

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.

Copy

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.

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoFocusbooleantrueFocuses the selected day automatically when the component mounts or updates.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
excludePastDatesboolean—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.
numOfMonthsnumber2Defines 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.
presetsPresetType[] | { 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.
refnull | 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.
shouldCloseOnSelectboolean—Specifies whether calendar should close on a day selection.
showMonthDropdownboolean—Specifies whether to display a month selection dropdown inside of a calendar.
showYearDropdownboolean—Specifies whether to display a year selection dropdown inside of a calendar.
valuestring | Date | DateRangeType—Defines a selected date or date range.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
calendarDriver—
presetsDropdownLayoutDriver—
isDropdownExists—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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) — 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)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?