Calendar

Components/Form/Calendar/Calendar

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

Overview

Copy

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.

Copy

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.

Copy

Date Indication

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

Copy

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.

Copy

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.

Copy

Select Month and Year

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

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.

Copy

Common use case examples

Event scheduling

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoFocus (required)booleantrueFocus selected day automatically when component mounts or updates.
containFocusboolean—Specifies whether focus is trapped in the calendar while autoFocus is enabled, and returned to the previously focused element when the calendar unmounts.
dataHookstring—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)booleanfalseSpecify 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
firstDayOfWeek0 | 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.
leftArrowAriaLabelstring—Defines a string value that labels the left arrow in calendar header.
leftArrowAriaLabelledBystring—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.
monthDropdownAriaLabelstring—Defines a string value that labels the months dropdown in calendar header.
monthDropdownAriaLabelledBystring—Identifies the element that labels the months dropdown in calendar header.
numOfMonths (required)1 | 21Allows 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.
rightArrowAriaLabelstring—Defines a string value that labels the right arrow in calendar header.
rightArrowAriaLabelledBystring—Identifies the element that labels the right arrow in calendar header.
rtlboolean—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)booleantrueSpecify whether the calendar closes on day selection.
showMonthDropdown (required)booleanfalseDisplays a selectable monthDropdown.
showYearDropdown (required)booleanfalseDisplays a selectable yearDropdown.
size (required)"small" | "medium"'medium'Defines calendar size property. It can be either small or medium (default)
todayDate—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.
valueDate | { from?: string | Date | undefined; to?: string | Date | undefined; }—Defines the selected date.
yearDropdownAriaLabelstring—Defines a string value that labels the years dropdown in calendar header.
yearDropdownAriaLabelledBystring—Identifies the element that labels the years dropdown in calendar header.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
close—
getCurrentMonthWithYear—
getNthWeekDayName—
clickOnNthDay—
clickDay—
isDayActive—
clickOnNthDayOfTheMonth—
clickOnSelectedDay—
clickOnYearDropdown—
clickOnMonthDropdown—
clickOnNthYear—
clickOnPrevMonthButton—
clickOnNextMonthButton—
keyboardNextYear—
keyboardPrevYear—
isHeaderExists—
isYearDropdownExists—
isYearCaptionExists—
isMonthDropdownExists—
isMonthCaptionExists—
getMonthCaption—
getMonthDropdownLabel—
getSelectedYear—
getFocusedDayReturns 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—
getSelectedDaysTODO: return Promise<Date[]> in the next major release (see docs/major-release.md)
getSizeReturns size property value currently set on component
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.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) — 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) — 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) — 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)
  • 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)
  • 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)
  • 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)
  • 1.98.0 (2024-03-15) — fix: arrows style (#13438)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?