The Date Picker§

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

$('.datepicker').pickadate()

{%= dateDemoField({ klass: 'js__datepicker' }) %}

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,
hiddenSuffix: '_submit',

// 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
})

{%= dateDemoField({ id: 'date_demo__weekdaysShort' }) %}

Buttons§

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

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

{%= dateDemoField({ id: 'date_demo__buttons' }) %}

Translations§

The picker can be extended to add support for internationalization. There are translations available for {%= grunt.file.expand( dirs.min.translations + '/*.js' ).length %} 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'
})

{%= dateDemoField({ id: 'date_demo__translations' }) %}

When using translations, make sure to also specify the formatSubmit and data-value.

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 a suffix:

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

{%= dateDemoField({ id: 'date_demo__formats--a' }).replace( 'type=text', 'name=date_demo__formats type=text' ) %}

When 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 into the various languages:

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

{%= dateDemoField({ id: 'date_demo__formats--b' }).replace( 'type=text', 'name=date_demo__formats type=text 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.

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
})

{%= dateDemoField({ id: 'date_demo__selectors--a' }) %}

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
})

{%= dateDemoField({ id: 'date_demo__selectors--b' }) %}

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
})

{%= dateDemoField({ id: 'date_demo__firstDay' }) %}

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)
})

{%= dateDemoField({ id: 'date_demo__limits--a' }) %}

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

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

{%= dateDemoField({ id: 'date_demo__limits--b' }) %}

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
})

{%= dateDemoField({ id: 'date_demo__limits--c' }) %}

Disable Dates§

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

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

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

{%= dateDemoField({ id: 'date_demo__disable-dates--a' }) %}

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

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

{%= dateDemoField({ id: 'date_demo__disable-dates--b' }) %}

3) 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],
        [2013,3,29]
    ]
})

{%= dateDemoField({ id: 'date_demo__disable-dates--c' }) %}

container§

Specify where to insert the picker’s root element by passing any valid CSS selector to this option:

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

{%= dateDemoField({ id: 'date_demo__container' }) %}

By default, the picker root is inserted right after the input element.

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)
    }
})

{%= dateDemoField({ id: 'date_demo__events' }).replace( 'Try me', 'Open your console and try me' ) %}

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”.