The Date Picker§

The basic setup requires targetting an `input` element and invoking the picker:

$('.datepicker').pickadate()

Along with v3, the v2 options and API have effectively been deprecated. Read up on the full changelog here.

One of the most critical changes is that the “month” used to create dates, just as in JavaScript’s native Date object, now has zero-as-index.

Options§

With the basic invocation above, these are the default settings:

// Strings and translations
monthsFull: ['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'],
weekdaysFull: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
weekdaysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
showMonthsShort: undefined,
showWeekdaysFull: undefined,

// Buttons
today: 'Today',
clear: 'Clear',

// Formats
format: 'd mmmm, yyyy',
formatSubmit: undefined,
hiddenPrefix: undefined,
hiddenSuffix: '_submit',

// Editable input
editable: undefined,

// Dropdown selectors
selectYears: undefined,
selectMonths: undefined,

// First day of the week
firstDay: undefined,

// Date limits
min: undefined,
max: undefined,

// Disable dates
disable: undefined,

// Root container
container: undefined,

// Events
onStart: undefined,
onRender: undefined,
onOpen: undefined,
onClose: undefined,
onSet: undefined,
onStop: undefined,

// Classes
klass: {

    // The element states
    input: 'picker__input',
    active: 'picker__input--active',

    // The root picker and states *
    picker: 'picker',
    opened: 'picker--opened',
    focused: 'picker--focused',

    // The picker holder
    holder: 'picker__holder',

    // The picker frame, wrapper, and box
    frame: 'picker__frame',
    wrap: 'picker__wrap',
    box: 'picker__box',

    // The picker header
    header: 'picker__header',

    // Month navigation
    navPrev: 'picker__nav--prev',
    navNext: 'picker__nav--next',
    navDisabled: 'picker__nav--disabled',

    // Month & year labels
    month: 'picker__month',
    year: 'picker__year',

    // Month & year dropdowns
    selectMonth: 'picker__select--month',
    selectYear: 'picker__select--year',

    // Table of dates
    table: 'picker__table',

    // Weekday labels
    weekdays: 'picker__weekday',

    // Day states
    day: 'picker__day',
    disabled: 'picker__day--disabled',
    selected: 'picker__day--selected',
    highlighted: 'picker__day--highlighted',
    now: 'picker__day--today',
    infocus: 'picker__day--infocus',
    outfocus: 'picker__day--outfocus',

    // The picker footer
    footer: 'picker__footer',

    // Today & clear buttons
    buttonClear: 'picker__button--clear',
    buttonToday: 'picker__button--today'
}

* It is important to not add any stylings to the picker’s root element. Instead, target the .picker__holder element (or any other within) based on the state of the root element.

Strings§

Change the month and weekday labels as you find suitable:

$('.datepicker').pickadate({
    weekdaysShort: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
    showMonthsShort: true
})

Buttons§

Change the text or hide a button completely by passing a false-y value:

$('.datepicker').pickadate({
    today: '',
    clear: 'Clear selection'
})

Translations§

The picker can be extended to add support for internationalization. There are translations available for 34 languages which you can include in one of two ways:

// Extend the default picker options for all instances.
$.extend($.fn.pickadate.defaults, {
    monthsFull: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
    weekdaysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
    today: 'aujourd\'hui',
    clear: 'effacer',
    formatSubmit: 'yyyy/mm/dd'
})

// Or, pass the months and weekdays as an array for each invocation.
$('.datepicker').pickadate({
    monthsFull: ['Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre'],
    weekdaysShort: ['Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam'],
    today: 'aujourd\'hui',
    clear: 'effacer',
    formatSubmit: 'yyyy/mm/dd'
})

When using translations, specify the formatSubmit and data-value to ensure the date parses correctly regardless of locale.

RTL languages§

For right-to-left (RTL) languages you’ll need to switch the arrows and text direction by linking along the rtl.css file:

<!-- Add the stylings after the pickadate theme files -->
<link rel="stylesheet" href="lib/themes/rtl.css">

<!-- Add the language after the pickadate script files -->
<script src="lib/translations/ar.js"></script>

Formats§

Display a human-friendly format and use an alternate one to submit.

This is done by creating a new hidden input element with the same name attribute as the original and an optional prefix/suffix:

$('.datepicker').pickadate({
    // Escape any “rule” characters with an exclamation mark (!).
    format: 'You selecte!d: dddd, dd mmm, yyyy',
    formatSubmit: 'yyyy/mm/dd',
    hiddenPrefix: 'prefix__',
    hiddenSuffix: '__suffix'
})

Pre-fill values using custom formats or translations§

When using a custom formatting rules for the format option or using translations, the input element should be given a data-value attribute formatted using the formatSubmit – the element’s value can be left blank. This helps to parse the date from custom formats into various languages:

<input data-value="2013/04/20">

Formatting Rules§

The following rules can be used to format any date:

Rule	Description	Result
`d`	Date of the month	1 – 31
`dd`	Date of the month with a leading zero	01 – 31
`ddd`	Day of the week in short form	Sun – Sat
`dddd`	Day of the week in full form	Sunday – Saturday
`m`	Month of the year	1 – 12
`mm`	Month of the year with a leading zero	01 – 12
`mmm`	Month name in short form	Jan – Dec
`mmmm`	Month name in full form	January – December
`yy`	Year in short form *	00 – 99
`yyyy`	Year in full form	2000 – 2999

* Avoid using the yy format within formatSubmit because it leads to assumptions that could parse inaccurately.

Editable input§

By default, typing into the input is disabled by giving it a readOnly attribute. Doing so ensures that virtual keyboards don’t pop open on touch devices. It is also a confirmation that formats passed to the server will be consistent.

However, this behavior can be changed using the editable option:

$('.datepicker').pickadate({
    editable: true
})

An important thing to note here is that this disables keyboard bindings on the input element, such as arrow keys opening the picker. You will have to add your own bindings as you see fit.

Dropdown Selectors§

Display select menus to pick the month and year. Anything truth-y enables the selectors and anything false-y switches them into labels:

$('.datepicker').pickadate({
    selectYears: true,
    selectMonths: true
})

Specify the number of years selectable using an even integer - half before and half after the year in focus:

$('.datepicker').pickadate({
    // `true` defaults to 10.
    selectYears: 4
})

First Weekday§

The first day of the week can be set to either Sunday or Monday. Anything truth-y sets it as Monday and anything false-y as Sunday:

$('.datepicker').pickadate({
    firstDay: 1
})

Date Limits§

Set the minimum and maximum selectable dates on the picker.

1) Using JavaScript date objects:

$('.datepicker').pickadate({
    min: new Date(2013,3,20),
    max: new Date(2013,7,14)
})

2) Using arrays formatted as [YEAR,MONTH,DATE]:

$('.datepicker').pickadate({
    min: [2013,3,20],
    max: [2013,7,14]
})

3) As dates relative to today using integers or a boolean:

$('.datepicker').pickadate({
    // An integer (positive/negative) sets it relative to today.
    min: -15,
    // `true` sets it to today. `false` removes any limits.
    max: true
})

Disable Dates§

Disable a specific or arbitrary set of dates selectable on the picker.

1) Using JavaScript Date objects:

$('.datepicker').pickadate({
    disable: [
        new Date(2013,3,13),
        new Date(2013,3,29)
    ]
})

2) Using arrays formatted as [YEAR,MONTH,DATE]:

$('.datepicker').pickadate({
    disable: [
        [2013,3,3],
        [2013,3,12],
        [2013,3,20]
    ]
})

3) Using integers representing days of the week (from 1 to 7):

$('.datepicker').pickadate({
    disable: [
        1, 4, 7
    ]
})

4) Disabling all except a specific or arbitrary set of dates by setting true as the first item in the collection:

$('.datepicker').pickadate({
    disable: [
        true,
        1, 4, 7,
        [2013,3,3],
        [2013,3,12],
        [2013,3,20],
        new Date(2013,3,13),
        new Date(2013,3,29)
    ]
})

5) Enabling/disabling ranges with exceptions by passing 'inverted' as the last parameter in the item within the collection:

$('.datepicker').pickadate({
    disable: [
        1,
        [2013, 10, 17, 'inverted']
    ]
})

container§

By default, the picker’s root element is inserted right after the input element. Specify where to insert the root element by passing any valid CSS selector to this option:

$('.datepicker').pickadate({
    container: '#root-outlet'
})

This is especially important when the input falls within a label element because click events bubble up to the label element and re-open the picker.

events§

Fire off events as the user interacts with the picker:

$('.datepicker').pickadate({
    onStart: function() {
        console.log('Hello there :)')
    },
    onRender: function() {
        console.log('Whoa.. rendered anew')
    },
    onOpen: function() {
        console.log('Opened up')
    },
    onClose: function() {
        console.log('Closed now')
    },
    onStop: function() {
        console.log('See ya.')
    },
    onSet: function(event) {
        console.log('Just set stuff:', event)
    }
})

Within scope of all six of these events, this refers to the picker.

The onSet event is the only callback that is passed an event argument that provides a bit of context as to which properties are being “set”.