Components/Form/Calendar/Calendar
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/calendar
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.
<DatePicker/> instead.<DatePicker/> instead.Change calendar's layout using `numOfMonths` prop. It can display 1 or 2 months.
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.
Mark important dates with `dateIndication` prop. It's helpful when the calendar needs to highlight the dates with happening events.
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.
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.
Let the user quickly change the month and year values with props::
 - `showMonthDropdown ` - enables month dropdown.
 - `showYearDropdown` - enables year dropdown.
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.
Use a calendar with time picker to let our users set the appointment date or article publish date.
| 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. |
Import the driver matching your test environment:
| 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. |
Last updated: 30 October 2026