Documentation

Air Datepicker has a large amount of options, which allows you to customize it to your needs. This page contains all the parameters with a detailed description that the calendar accepts.

Options

classes
string

Adds extra classes to the calendar.

inline
boolean
false

Makes the calendar to be permanently visible

locale
object
locale/ru

Language of the calendar. Available locales are in air-datepicker/locale/.

For more information about the localization structure, see in corresponding section.

import AirDatepicker from 'air-datepicker';
import localeEn from 'air-datepicker/locale/en';

new AirDatepicker('#el', {
    locale: localeEn
})
startDate
Date | string | number
new Date()

Sets the start view date of calendar.

firstDay
number

The index of the day from which the week begins. Possible values are from 0 (Sunday) to 6 (Saturday). By default, it is taken from the localization, if the value is passed here, it will have a higher priority.

weekends
array
[6, 0]

Indexes of the days that will be considered a weekend. The .-weekend- class will be added to them. By default, this is Saturday and Sunday.

isMobile
boolean
false

If true, then the calendar will appear as a modal window with slightly enlarged dimensions.

visible
boolean
false

Shows the calendar immediately after initialization.

dateFormat
string | (date) => string
""

Date format. Since version 3, the date format is based on the Unicode Technical Standard #35 standard. By default, it is taken from the current locale. The value passed here will have a higher priority.

Available tokens:

T — time in milliseconds
E — the short name of the day of the week, the daysShort field from the locale
EEEE — the full name of the day of the week, the days field from the locale
d — day of the month
dd — day of the month with leading zero
M — number of the month
MM — number of the month with leading zero
MMM — short name of the month, the monthsShort field from the locale
MMMM — full name of the month, field months from the locale
yy — two-digit year number
yyyy — full year number
yyyy1 — the first year in current decade
yyyy2 — the last year in current decade

You can also pass a function here to manually process the selected dates. It should return a string. If the multi-date selection mode is enabled, array of selected dates will be passed to this function.

new AirDatepicker('#el', {
    dateFormat(date) {
        return date.toLocaleString('ja', {
            year: 'numeric',
            day: '2-digit',
            month: 'long'
        });
    }
})
altField
string | DOMNode
""

An additional text field where the date with the format from the altFieldDateFormat field will be written

altFieldDateFormat
string | (date) => string
"T"

Date format for alternative field

toggleSelected
boolean
true

If true, then clicking on the active cell will remove the selection from it

keyboardNav
boolean
true

Enables keyboard navigation. It only works if the element on which the calendar is initialized is a text field.

Key combinations:

Ctrl + → | ↑ — next month
Ctrl + ← | ↓ — previous month
Shift + → | ↑ — next year
Shift + ← | ↓ — previous year
Alt + → | ↑ — 10 years forward
Alt + ← | ↓ — 10 years backward
Ctrl + Shift + ↑ — change calendar view, from dates to decades
Esc — closes calendar
selectedDates
Date[] | string[] | number[]
false

Array of active dates. Accepts both separate data types and mixed data types. If an invalid date format is passed, this value will be ignored

import AirDatepicker from 'air-datepicker';

let startDate = new Date('2021-07-20');

new AirDatepicker('#el', {
    startDate,
    multipleDates: true,
    selectedDates: [startDate, '2021-07-25', 1626307200000]
})
container
string | HTMLElement
""

Parent element for the calendar. By default all calendars are placed in element with class name .air-datepicker-global-container.

position
string | function
"bottom left"

Position of the calendar relative to the text field.

If it is a string then the first value is position along the main axis, the second is position along the secondary one. For example, {position: 'top right'} - set the calendar position to the top right of the text field.

If you pass the function, you can adjust the position yourself - it will be called when the show() method is triggered. But in this case, all transitions are disabled and you will have to add them manually if they are required. The function accepts an object from the following fields

$datepicker
HTMLDivElement
 — calendar element
$target
HTMLInputElement
 — target element on which calendar is initialized
$pointer
HTMLElement
 — an arrow pointing to the target element
isViewChange
boolean
 — since the calendar is also positioned during the view change, this field allows you to determine at what point the function is called - when calendar appears or when switching from one view to another
done
() => void
 — the function that should be called at the end, in case of manual handling of hiding the calendar

If manual processing of calendar hiding is required, then you can return the function from position - it will be called when hide() is triggered - upon completion of processing, do not forget to call the done function to complete the hiding process.

Example of manual positioning:

new AirDatepicker('#el', {
    autoClose: true,
    position({$datepicker, $target, $pointer}) {
        let coords = $target.getBoundingClientRect(),
            dpHeight = $datepicker.clientHeight,
            dpWidth = $datepicker.clientWidth;
    
        let top = coords.y + coords.height / 2 + window.scrollY - dpHeight / 2;
        let left = coords.x + coords.width / 2 - dpWidth / 2;
    
        $datepicker.style.left = `${left}px`;
        $datepicker.style.top = `${top}px`;
    
        $pointer.style.display = 'none';
    }
})
view
string
"days"

The initial view of the calendar. Possible values:

days — displaying days of one month
months — displaying months of one yea
years — displaying the years of one decade
minView
string
"days"

The minimum possible representation of the calendar. It is used, for example, when you need to provide only a choice of the month. The possible values are the same as for view

showOtherMonths
boolean
true

If true, dates from other months will be displayed in days view.

selectOtherMonths
boolean
true

If true, it will be possible to select dates from other months.

moveToOtherMonthsOnSelect
boolean
true

If true, then selecting dates from another month will be causing transition to this month.

minDate
Date | string | number
""

The minimum possible date to select.

maxDate
Date | string | number
""

The maximum possible date to select.

disableNavWhenOutOfRange
boolean
true

Whether it is necessary to prohibit switching to the next or previous month/year/decade if they go beyond the minimum or maximum dates.

If true, then calendar navigation buttons will be deactivated if such case occurs.

multipleDates
boolean | number
false

If true, then you can select an unlimited number of dates. If you pass a number, the number of selected dates will be limited by it's value.

multipleDatesSeparator
string
", "

Separator between dates in text field. It is used in the multiple date selection mode and in the range mode.

range
boolean
false

Provides the ability to select a date range. The value from multipleDatesSeparator will be used as the separator.

dynamicRange
boolean
true

If true, then after selecting dates in range mode, they can be changed by dragging them.

buttons
string | string[] | object | object[] | false
false

This option allows you to add action buttons to body of the calendar. You could add two pre installed buttons or create your own.

Initially two buttons are available:

today — "Today" button - clicking on it will perform transition to today date
clear — "Clear" button - clicking on it will clear all selected dates

To create your own button you should pass and object of the following type:

ButtonShape = {
    content: string | (dpInstance) => string
    tagName?: string
    className?: string
    attrs?: object
    onClick?: (dpInstance) => void
}

Example of custom button

import AirDatepicker from 'air-datepicker';

let button = {
    content: 'Select 2021-07-26',
    className: 'custom-button-classname',
    onClick: (dp) => {
        let date = new Date('2021-07-26');
        dp.selectDate(date);
        dp.setViewDate(date);
    }
}

new AirDatepicker('#el', {
    buttons: [button, 'clear'] // Custom button, and pre-installed 'clear' button
})
monthsField
string
"monthsShort"

A field from the localization object that will be used to display the names of the month in the months view.

showEvent
string
"focus"

DOM event on which calendar will be shown.

autoClose

If true, the calendar will be hidden after selecting the date.

prevHtml
string
"<svg><path d="M 17,12 l -5,5 l 5,5"></path></svg>"

"Previous" button content.

nextHtml
string
"<svg><path d="M 14,12 l 5,5 l -5,5"></path></svg>"

"Next" button content.

Title templates in the calendar navigation. You can use HTML tags and tokens from dateFormat. You can also pass the function as a value - it will receive an instance of the calendar as an argument, and should return a string.

If a callback function is passed, it will be called every time the view changes, the date is selected, or when switching to another month.

Default values are:

let navTitlesDefaults = {
    days: 'MMMM, <i>yyyy</i>',
    months: 'yyyy',
    years: 'yyyy1 - yyyy2'
}

Usage:

new AirDatepicker('#el', {
    navTitles: {
        days: '<strong>Choose date</strong> MM, yyyy'
    }
})
timepicker
boolean
false

Turns on timepicker

onlyTimepicker
boolean
false

If you need to choose only time, without date.

dateTimeSeparator
string
" "

Separator between date and time.

timeFormat
string

Time format. Just like dateFormat relies on Unicode Technical Standard #35. If you pass a 12-hour display format, the time sliders will be automatically adjusted to the corresponding mode.

Possible symbols:

h — hours in 12-hour mode
hh — hours in 12-hour mode with leading zero
H — hours in 24-hour mode
HH — hours in 24-hour mode with leading zero
m — minutes
mm — minutes with leading zero
aa — day period lower case
AA — day period upper case
minHours
number
0

Minimum possible hours value.

maxHours
number
24

Maximum possible hours value.

minMinutes
number
0

Minimum possible minutes value.

maxMinutes
number
59

Maximum possible minutes value.

hoursStep
number
1

Hours step.

minutesStep
number
1

Minutes step.

Localization

Starting from version 3.0.0, the calendar language must be passed as an object, instead of a string, as it was before. You can pass one of the available localizations or create your own. The available localizations are located in the 'locales/' directory

Example of localization object

export default {
    days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    daysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    daysMin: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
    months: ['January','February','March','April','May','June', 'July','August','September','October','November','December'],
    monthsShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    today: 'Today',
    clear: 'Clear',
    dateFormat: 'mm/dd/yyyy',
    timeFormat: 'hh:ii aa',
    firstDay: 0
};

Events

onSelect
({date, formattedDate, datepicker}) => void

Event which is triggered when selecting or deselecting date. It takes object as an argument consist of next fields:

date
Date | Date[]
 — selected date, if multiple date mode is on, then array of dates will be passed.
formattedDate
string | string[]
 — formatted selected date, or array in case of multiple dates mode.
datepicker
AirDatepicker
 — calendar instance
onChangeViewDate
({month, year, decade}) => void

Triggered when navigating back and forth. It takes object as and argument with actual values of month, year and decade

month
number
 — month of viewed date
year
number
 — year of viewed date
decade
number[]
 — decade of viewed date. The first element is the start year of decade, the second one - the end of decade.
onChangeView
("days | months | years") => void

When changing the view, for example, from days to months, this function will be called. The name of the current view will be passed as an argument.

onRenderCell
({date, cellType, datepicker}) => {html, classes, disabled, attrs}

A function that will be called every time a calendar cell is drawn. It is used if you need to customize the cell in some way, change the contents or make it unavailable for selection.

It takes object as an argument which is describing current cell:

date
Date
 — date of current cell
cellType
"day | month | year"
 — cell type - day, month or year
datepicker
AirDatepicker
 — calendar instance

This function must return an object, consist of next fields:

html
string
 — custom cell content
classes
string
 — extra classes
disabled
boolean
 — if cell should be disabled
attrs
Record<string, string | number | undefined>
 — object with extra cell attributes for a cell
new AirDatepicker('#el', {
    onRenderCell({date, cellType}) {
        // Disable all 12th dates in month
        if (cellType === 'day') {
            if (date.getDate() === 12) {
                return {
                    disabled: true,
                    classes: 'disabled-class'
                    attrs: {
                        title: 'Cell is disabled'
                    }
                }
            }
        }
    }
})
onShow
(isFinished) => void

Callback function when the calendar appears. Called at the beginning of the animation, and when the animation has finished.

isFinished
boolean
 — animation completion indicator
onHide
(isFinished) => void

Callback function when closing the calendar. Called at the beginning of the hide animation, and when the animation has finished.

isFinished
boolean
 — animation completion indicator
onClickDayName
({dayIndex, datepicker}) => void

Adds possibility to click on the names of days in calendar. In case callback is passed `-clickable-` will be added to those elements

dayIndex
index
 — day of week index, where is 0 - Sunday, 6 - Saturday
datepicker
AirDatepicker
 — calendar instance