Options

All options are passed as the second argument to new Datepicker(el, options).

Core

Option	Type	Default	Description
format	string	'YYYY-MM-DD'	Date format string. Tokens: YYYY MM DD HH mm ss.
locale	string | LocaleConfig	'sk'	Locale identifier or full locale config object.
value	string | Date	—	Initial selected date.
defaultValue	string | Date	—	Alias for value (used when value is uncontrolled).
mode	'single' | 'range' | 'multiple'	'single'	Selection mode.
theme	'light' | 'dark' | 'auto'	'auto'	Color theme.

Constraints

Option	Type	Default	Description
minDate	string | Date	—	Earliest selectable date. Cells before this date are visually disabled and not clickable.
maxDate	string | Date	—	Latest selectable date. Cells after this date are visually disabled and not clickable.
minDateTitle	string	locale default	Tooltip shown on cells that fall before minDate. Overrides the locale string.
maxDateTitle	string	locale default	Tooltip shown on cells that fall after maxDate. Overrides the locale string.
disabledDates	Date[] | ((d: Date) => boolean | Promise<boolean>)	—	Specific dates or predicate to disable.
disabledWeekdays	number[]	[]	Weekday indices to disable (0=Sun … 6=Sat).
maxRangeDays	number	0	Max span of a range selection (0 = unlimited).
minRangeDays	number	0	Min span of a range selection.
maxSelections	number	0	Max number of multiple selections (0 = unlimited).

Display

Option	Type	Default	Description
position	'auto' | 'top' | 'bottom' | 'left' | 'right'	'auto'	Dropdown placement.
zIndex	number	1000	z-index of the dropdown.
animation	'fade' | 'slide' | 'none'	'fade'	Open/close animation.
inline	boolean	false	Render calendar inline (always visible).
numberOfMonths	number	1	Number of months visible side-by-side.
fixedHeight	boolean	false	Always render 6 rows (prevents layout shift).
showWeekNumbers	boolean	false	Show ISO week number column.
weekNumberSystem	'iso' | 'us'	'iso'	Week numbering system.
weekStart	0-6	locale default	First day of week (0=Sun, 1=Mon …).
weekdayFormat	'short' | 'narrow' | 'long'	'short'	Weekday header format.
showTodayButton	boolean	false	Show "Today" footer button.
showClearButton	boolean	false	Show "Clear" footer button.
showConfirmButton	boolean	false	Show "OK" confirm button (defers selection).
showCancelButton	boolean	false	Show "Cancel" button.
showToggleIcon	boolean	true	Show calendar icon in input (via CSS).
showHeader	boolean	true	Show month/year navigation header.
highlightedDates	Date[]	—	Dates to mark with vdp-cell--highlighted class.

Behaviour

Option	Type	Default	Description
openOnFocus	boolean	true	Open dropdown on input focus.
closeOnSelect	boolean	true	Close after date selection.
allowManualInput	boolean	true	Allow typing in the input field.
readonlyInput	boolean	false	Make input read-only.
autofill	boolean	true	Parse + format raw input on blur.
strictMode	boolean	false	Fire vdp:invalid on blur if text can't be parsed.
emptyOk	boolean	true	Allow empty value.
keepFocus	boolean	false	Return focus to the input after close (only when the calendar held focus). See Keyboard & focus.
initialView	'days' | 'months' | 'years'	'days'	Which view to open on.
container	HTMLElement	document.body	Portal target for the dropdown.

Callbacks

Every callback below is read at the moment its event fires, so all of them can be added, swapped or removed on a live instance with setOptions() — passing undefined unregisters one.

Option	Signature	Description
onOpen	({ month, from, to }: OpenRange) => void | Promise<void>	Called once when calendar opens. month = 1st of displayed month; from/to = full visible grid range. Awaited before onCellRender.
onMonthChange	({ month, from, to }: OpenRange) => void | Promise<void>	Called on every month navigation (not on initial open). Same shape as onOpen. Awaited before onCellRender.
onClose	(reason: CloseReason) => void	Called when calendar closes.
onChange	(value: string, event: DatepickerChangeEvent) => boolean | void | Promise<boolean | void>	Called when selected date changes. Return false (or Promise<false>) to keep the calendar open — useful for async validation that fails after the value is set.
onInput	(raw: string) => void	Called on every keystroke in the input.
onInvalid	(error: DatepickerError) => void	Called when an invalid value is rejected.
onViewChange	(view: CalendarView) => void	Called when the calendar view changes.
onYearChange	(year: number) => void	Called when the displayed year changes.
onCellRender	(ctx: CellRenderContext) => CellRenderResult | Promise<CellRenderResult>	Called per visible day cell for async customisation.
onBeforeOpen	() => boolean | Promise<boolean>	Return false to cancel opening.
onBeforeChange	(next: Date, prev: Date | null) => boolean | Promise<boolean>	Return false to cancel selection.
onBeforeMonthChange	(next: Date, prev: Date) => boolean | Promise<boolean>	Return false to cancel navigation.
validate	(date: Date) => boolean | string | Promise<boolean | string>	Custom validation; return false or error string to reject.

Keeping the calendar open from onChange

Return false (or a Promise resolving to false) from onChange to prevent the calendar from closing after a date is selected. This is useful when you run async validation after the value is committed and need to give the user a chance to correct their choice.

new Datepicker('#dp', {
  format: 'YYYY-MM-DD',
  onChange: async (value, event) => {
    const isValid = await myServerValidate(event.date);
    if (!isValid) {
      showError('This date is not available');
      return false; // calendar stays open
    }
    // returning nothing (or void) closes the calendar normally
  },
});

Outside-click / Escape protection while onChange is pending

While onChange is awaited (e.g. your handler shows a confirm dialog), the calendar is automatically protected from being closed by an outside click or the Escape key. Any such close attempt is silently blocked until onChange resolves. Only a programmatic dp.close() call will still work.

This means you can safely show a modal or confirm() dialog inside onChange without the calendar disappearing under it:

onChange: async (value, event) => {
  try {
    // Calendar stays open while the user decides in the dialog,
    // even if they click outside the calendar.
    await showConfirmDialog('Is this date correct?');
  } catch {
    dp.setValue('');
    return false; // user cancelled — keep calendar open
  }
},

Note: The value is already applied to the input before onChange is called. If validation fails and you want to also clear the value, call dp.setValue('') inside the handler before returning false.

Difference from onBeforeChange: onBeforeChange runs before the value is set and prevents the commit entirely. onChange runs after the value is set and can only prevent the calendar from closing — the value change itself has already happened.

Appearance

Option	Type	Description
classNames	Partial<ClassNames>	Override any default class name. See Theming.
prevButtonContent	string	HTML string for the previous-month button (default: built-in SVG arrow). Accepts a Unicode character, plain text, or an SVG string.
nextButtonContent	string	HTML string for the next-month button (default: built-in SVG arrow). Accepts a Unicode character, plain text, or an SVG string.

Custom navigation arrows

Pass any HTML string — a Unicode character, text, or an inline SVG — to replace the default arrow icons:

// Unicode characters
new Datepicker('#dp', {
  prevButtonContent: '‹',
  nextButtonContent: '›',
});

// Double angle quotes
new Datepicker('#dp', {
  prevButtonContent: '«',
  nextButtonContent: '»',
});

// Inline SVG
new Datepicker('#dp', {
  prevButtonContent: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="15 18 9 12 15 6"/></svg>',
  nextButtonContent: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="9 18 15 12 9 6"/></svg>',
});