Settings

type

Type: String

Default: 'default'

Options: 'default' | 'multiple' | 'month' | 'year' | 'week'

new Calendar('#calendar', {
  type: 'default',
});

The type parameter defines the type of calendar displayed. The week type shows a single week rather than a whole month. It works on its own or with enableCollapse, which lets visitors switch between the month and week views.

inputMode

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  inputMode: true,
});

The inputMode parameter indicates that the mainElement, passed as the first parameter, represents an input field rather than a wrapper for the calendar.

openOnFocus

Type: Boolean | Function

Default: true

Options: true | false | () => false

new Calendar('#calendar', {
  openOnFocus: false,
  // or with a callback
  openOnFocus: (self) => !self.context.isShowInInputMode,
});

If the openOnFocus parameter is true or the callback returns true, then focusing the input will open the calendar. Use false or a callback to control this behavior and implement your own focus handler.

positionToInput

Type: String

Default: 'left'

new Calendar('#calendar', {
  positionToInput: 'auto',
  // positionToInput: ['bottom', 'center'],
});

This parameter defines the position of the calendar relative to the input if the calendar is initialized with the inputMode parameter.

positionToInput accepts a string with the value 'left', 'center', or 'right', or an array of values [Y-axis, X-axis], where the Y-axis can be 'bottom' or 'top', and the X-axis can be 'left', 'center', or 'right'. If the Y-axis is not specified, the default value 'bottom' is used.

You can use the value positionToInput: 'auto' to automatically determine the best position based on the available space in the viewport. The option allows calculating the available space on all 4 sides and will first try to display the calendar below the input, which is the default position. If there is not enough space below, it will evaluate another best available position.

animationNew

Type: Boolean | Object

Default: false

Options: true | false | { duration?: Number, easing?: String, slide?: Timing, fade?: Timing, collapse?: Timing }

Timing: { duration?: Number, easing?: String }

new Calendar('#calendar', {
  animation: true,
  // animation: { duration: 400, easing: 'ease-out' },
  // animation: { slide: { duration: 400 }, fade: { duration: 120 }, collapse: { duration: 300 } },
});

Animates transitions between views. Arrow navigation and enableSwipe use a horizontal slide, the month and year pickers cross-fade, and enableCollapse animates the calendar between its month and week heights.

Defaults differ per transition — 250ms for the slides, 150ms for the cross-fade and 300ms for collapsing, all with cubic-bezier(0.4, 0, 0.2, 1). An object overrides any of them: duration is in milliseconds, and easing accepts a CSS easing function. Values at the top level apply to every transition; nest them under slide (arrows and enableSwipe), fade (pickers) or collapse (enableCollapse) to target one group. Nested values win over top-level values.

Animated settling is skipped when the visitor asks for reduced motion through prefers-reduced-motion: reduce. Gestures still follow the pointer, but commit or return immediately on release.

The default is false for backwards compatibility: the option was added later, and turning it on changes what a DOM query sees during slide and cross-fade transitions. Their outgoing content stays in the DOM inside an inert [data-vc-ghost] layer, so date elements can briefly be present twice. Exclude that layer if your own code queries them; collapsing does not create a ghost layer.

firstWeekday

Type: Number

Default: 1

Options: from 0 to 6

new Calendar('#calendar', {
  firstWeekday: 1,
});

This parameter sets the first day of the week. Specify a number from 0 to 6, where the number represents the day of the week identifier. According to JS standards, the days of the week start with 0, and 0 is Sunday.

monthsToSwitch

Type: Number

Default: 1

Options: from 1 to 12

new Calendar('#calendar', {
  monthsToSwitch: 1,
});

The monthsToSwitch parameter controls the number of switchable months.

When monthsToSwitch is greater than 1, the month picker view will also only allow selecting months that are reachable from the currently selected month in steps of monthsToSwitch — other months will appear disabled. This keeps navigation consistent with the configured step size (most relevant together with displayMonthsCount in type: 'multiple', where it keeps multiple visible months in sync).

themeAttrDetect

Type: String | false

Default: 'html[data-theme]'

Options: string | false

new Calendar('#calendar', {
  themeAttrDetect: 'html[data-theme]',
});

To have the calendar automatically track and apply the site's theme, you can pass a string value in the form of a CSS selector. Square brackets indicate an attribute containing the theme name. By default, the html tag with the data-theme attribute is tracked, but you can configure any other attribute and tag, for example, class, if the class name is used to set the theme: 'html[class]'. If set to false, the theme will be determined by the user's system or the selectedTheme parameter.

locale

Type: String

Default: 'en'

Options: Language label | Array<locale>

new Calendar('#calendar', {
  locale: 'en',
  // Or specify an object for your labels
  // locale: {
  //   months: {
  //     long: [],
  //     short: [],
  //   },
  //   weekday: {
  //     long: [],
  //     short: [],
  //   }
  // },
});

This parameter sets the language localization of the calendar. You can specify a language label according to BCP 47 or provide arrays of month and weekday names, see more details here.

dateToday

Type: Date object

Default: 'today'

Options: Date | number | 'YYYY-MM-DD' | 'today'

new Calendar('#calendar', {
  dateToday: 'today',
});

The dateToday parameter defines which day will be considered today for the calendar.

dateMin

Type: String

Default: '1970-01-01'

Options: Date | number | 'YYYY-MM-DD' | 'today'

new Calendar('#calendar', {
  dateMin: '1970-01-01',
});

The dateMin parameter sets the minimum allowable date that the calendar will consider and which cannot be less than this date.

dateMax

Type: String

Default: '2470-12-31'

Options: Date | number | 'YYYY-MM-DD' | 'today'

new Calendar('#calendar', {
  dateMax: '2470-12-31',
});

The dateMax parameter sets the maximum allowable date that the calendar will consider and which cannot be greater than this date.

displayDateMin

Type: String

Default: '1970-01-01'

Options: Date | number | 'YYYY-MM-DD' | 'today'

new Calendar('#calendar', {
  displayDateMin: '2022-07-01',
});

This parameter sets the minimum date that the user can select. Dates earlier than the specified date will be disabled and unavailable for selection.

It is important to note that displayDateMin and displayDateMax disable dates outside the range, while dateMin and dateMax do not create them at all.

Passing null to displayDateMin in .set() explicitly resets it back to its default value. Passing undefined (e.g. omitting the property) leaves the current value unchanged.

displayDateMax

Type: String

Default: '2470-12-31'

Options: Date | number | 'YYYY-MM-DD' | 'today'

new Calendar('#calendar', {
  displayDateMax: '2024-07-01',
});

This parameter sets the maximum date that the user can select. Dates later than the specified date will be disabled and unavailable for selection.

It is important to note that displayDateMin and displayDateMax disable dates outside the range, while dateMin and dateMax do not create them at all.

Passing null to displayDateMax in .set() explicitly resets it back to its default value. Passing undefined (e.g. omitting the property) leaves the current value unchanged.

displayDatesOutside

Type: Boolean

Default: true

Options: true | false

new Calendar('#calendar', {
  displayDatesOutside: false,
});

With this parameter, you can decide whether to display days from the previous and next month.

displayDisabledDates

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  displayDisabledDates: false,
});

This parameter determines whether all days, including disabled days, will be displayed.

displayMonthsCount

Type: Number

Default: 2

Options: from 2 to 12

new Calendar('#calendar', {
  displayMonthsCount: 2,
});

The displayMonthsCount parameter defines the number of months displayed if the calendar type is set to 'multiple'.

disableDates

Type: String[] | Number[] | Date[]

Default: null

Options: ['YYYY-MM-DD'] | [Number] | [Date] | null

new Calendar('#calendar', {
  disableDates: ['2022-08-10:2022-08-15', '2022-08-20', 1722152977141, new Date()],
});

This parameter allows you to disable specified dates, regardless of the specified range.

To specify a date range, use any delimiter between dates within a single string.

disableAllDates

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  disableAllDates: true,
});

This parameter disables all days and can be useful when using enableDates.

disableDatesPast

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  disableDatesPast: true,
});

This parameter disables all past days.

disableDatesGaps

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  disableDatesGaps: true,
});

This parameter disables the selection of days within a range with disabled dates. It only works if the selectionDatesMode parameter is set to 'multiple-ranged'.

disableWeekdays

Type: Number

Default: []

Options: from 0 to 6

new Calendar('#calendar', {
  disableWeekdays: [0, 6],
});

This parameter allows you to disable specified weekdays. Specify an array with numbers from 0 to 6, where each number represents a day of the week identifier. According to JS standards, the days of the week start with 0, and 0 is Sunday.

disableToday

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  disableToday: true,
});

With this parameter, you can disable the selection of today's date in the calendar.

enableDates

Type: String[] | Number[] | Date[]

Default: null

Options: ['YYYY-MM-DD'] | [Number] | [Date] | null

new Calendar('#calendar', {
  enableDates: ['2022-08-11:2022-08-16', '2022-08-20', 1722152977141, new Date()],
});

This parameter allows you to enable specified dates, regardless of the range and disabled dates.

To specify a date range, use any delimiter between dates within a single string.

enableEdgeDatesOnly

Type: Boolean

Default: true

Options: true | false

new Calendar('#calendar', {
  enableEdgeDatesOnly: true,
});

This parameter allows you to get only the start and end dates selected by the user, ignoring intermediate dates. This parameter only works if selectionDatesMode is set to 'multiple-ranged'.

It is important to note that when using this parameter, disabled dates within the date range will have no effect. Therefore, use this option only if you are interested in the start and end dates selected by the user.

enableDateToggle

Type: Boolean | Function

Default: true

Options: true | false | () => false

new Calendar('#calendar', {
  enableDateToggle: false,
  // or with a callback
  enableDateToggle: (self) => new Date(self.selectedDates[0]) < new Date(),
});

If the enableDateToggle parameter is true or the callback returns true, then clicking on a selected date again will deselect it.

enableWeekNumbers

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  enableWeekNumbers: true,
});

With this parameter, you can decide whether to display week numbers in the year.

enableMonthChangeOnDayClick

Type: Boolean

Default: true

Options: true | false

new Calendar('#calendar', {
  enableMonthChangeOnDayClick: false,
});

With this parameter, you can decide whether the month will switch when clicking on a day from the previous or next month.

enableJumpToSelectedDate

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  enableJumpToSelectedDate: true,
  selectedDates: ['2018-05-02'],
});

If this option is enabled and one or more selected dates are specified, but without specifying selectedMonth and selectedYear, the calendar will jump to the first selected date. If set to false, the calendar will always open for the current month and year.

This option has no effect if selectedMonth and selectedYear are specified.

enableCollapseNew

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  enableCollapse: true,
});

Adds a control under the grid that folds the month down to one week and unfolds it again. The week is anchored to the first selected date when it belongs to the displayed month, otherwise to today when it belongs to that month, and otherwise to the first day of the displayed month. The control is a chevron on devices with a mouse and a grabber on touch devices, which can be dragged up and down.

enableCollapse does not require enableSwipe or animation. Collapsing switches type to 'week', so reading calendar.type tells you the current state, and set({ type: 'week' }) does the same thing without the transition. Only the default and week types support this option; other types throw during init().

enableSwipeNew

Type: Boolean

Default: false

Options: true | false

new Calendar('#calendar', {
  enableSwipe: true,
});

Lets the visitor drag the calendar content sideways to reach the next or previous period in every view the arrows can navigate — default, multiple, week and the year list. The neighbouring period follows the pointer. Release distance and velocity decide whether it settles into place or returns.

enableSwipe does not require enableCollapse or animation; without animation, release settles immediately. Vertical scrolling over the calendar is left to the page, and a swipe is available only while the corresponding arrow is visible, so it observes dateMin, dateMax and navigation restrictions. The drag does not select the date it ends on.

selectionDatesMode

Type: String | false

Default: 'single'

Options: 'single' | 'multiple' | 'multiple-ranged' | false

new Calendar('#calendar', {
  selectionDatesMode: 'single',
});

This parameter determines whether selecting one or multiple days is allowed, or if date selection is completely disabled.

selectionMonthsMode

Type: Boolean

Default: true

Options: true | false | 'only-arrows'

new Calendar('#calendar', {
  selectionMonthsMode: false,
});

This parameter allows you to disable month selection, allow month switching only with arrows, or allow month switching in any way.

selectionYearsMode

Type: Boolean

Default: true

Options: true | false | 'only-arrows'

new Calendar('#calendar', {
  selectionYearsMode: false,
});

This parameter allows you to disable year selection, allow year switching only with arrows, or allow year switching in any way.

selectionTimeMode

Type: false | Number

Default: false

Options: false | 24 | 12

new Calendar('#calendar', {
  selectionTimeMode: true,
});

This parameter enables time selection. You can also specify the time format using a number: 24-hour or 12-hour format.

selectedDates

Type: String[] | Number[] | Date[]

Default: null

Options: ['YYYY-MM-DD'] | [Number] | [Date] | null

new Calendar('#calendar', {
  selectedDates: ['2022-08-10:2022-08-15', '2022-08-20', 1722152977141, new Date()],
});

This parameter allows you to specify a list of dates that will be selected when the calendar is initialized.

To specify a date range, use any delimiter between dates within a single string.

selectedMonth

Type: Number

Default: null

Options: from 0 to 11 | null

new Calendar('#calendar', {
  selectedMonth: 0,
});

This parameter defines the month that will be displayed when the calendar is initialized. According to JS standards, months are numbered from 0 to 11. See enableJumpToSelectedDate to default to the first selected date.

selectedYear

Type: Number

Default: null

Options: Number (YYYY) | null

new Calendar('#calendar', {
  selectedYear: 2022,
});

This parameter defines the year that will be displayed when the calendar is initialized. See enableJumpToSelectedDate to default to the first selected date.

selectedHolidays

Type: String[] | Number[] | Date[]

Default: null

Options: ['YYYY-MM-DD'] | [Number] | [Date] | null

new Calendar('#calendar', {
  selectedHolidays: ['2022-08-10:2022-08-15', '2022-08-20', 1722152977141, new Date()],
});

This parameter allows you to specify dates that will be considered holidays and will receive an additional data attribute for styling.

To specify a date range, use any delimiter between dates within a single string.

selectedWeekends

Type: Number

Default: [0, 6]

Options: number[0-6]

new Calendar('#calendar', {
  selectedWeekends: [0, 6],
});

This parameter allows you to specify the weekend days of the week. Specify an array with numbers from 0 to 6, where each number represents a day of the week identifier. According to JS standards, the days of the week start with 0, and 0 is Sunday.

selectedTime

Type: String

Default: null

Options: 'hh:mm aa' | null

new Calendar('#calendar', {
  selectedTime: '03:44 AM',
});

This parameter allows you to set the time that will be displayed when the calendar is initialized. The time is set in the format 'hh:mm aa', where 'aa' is the AM/PM marker. If using the 24-hour format, the 'aa' marker is not required.

selectedTheme

Type: String

Default: 'system'

Options: string (custom theme) | 'light' | 'dark' | 'system'

new Calendar('#calendar', {
  selectedTheme: 'system',
});

This parameter defines the theme of the calendar. By default, the theme is determined by the user's system or the site settings.

timeMinHour

Type: Number

Default: 0

Options: from 0 to 23

new Calendar('#calendar', {
  timeMinHour: 0,
});

This parameter specifies which hour will be the minimum for selection.

timeMaxHour

Type: Number

Default: 23

Options: from 0 to 23

new Calendar('#calendar', {
  timeMaxHour: 23,
});

This parameter specifies which hour will be the maximum for selection.

timeMinMinute

Type: Number

Default: 0

Options: from 0 to 59

new Calendar('#calendar', {
  timeMinMinute: 0,
});

This parameter specifies which minute will be the minimum for selection.

timeMaxMinute

Type: Number

Default: 59

Options: from 0 to 59

new Calendar('#calendar', {
  timeMaxMinute: 59,
});

This parameter specifies which minute will be the maximum for selection.

timeControls

Type: String

Default: 'all'

Options: 'all' | 'range'

new Calendar('#calendar', {
  timeControls: 'all',
});

This parameter defines the method of time selection: 'all' (any method) or 'range' (only with the controller).

timeStepHour

Type: Number

Default: 1

Options: from 1 to 23

new Calendar('#calendar', {
  timeStepHour: 1,
});

This parameter sets the step for the hour controller.

timeStepMinute

Type: Number

Default: 1

Options: from 1 to 59

new Calendar('#calendar', {
  timeStepMinute: 1,
});

This parameter sets the step for the minute controller.

sanitizerHTML

Type: Function

Default: (html) => html

import DOMPurify from 'dompurify';
 
new Calendar('#calendar', {
  sanitizerHTML: (html) => DOMPurify.sanitize(html),
});

sanitizerHTML can sanitize HTML templates to make them safe for CSP.

Note that the example uses the third-party library

dompurify

. sanitizerHTML is not required for the calendar to function.