# 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',

    // Accessibility labels
    labelMonthNext: 'Next month',
    labelMonthPrev: 'Previous month',
    labelMonthSelect: 'Select a month',
    labelYearSelect: 'Select a year',

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

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

## Accessibility labels§

Change the `title` attributes to several elements within the picker:

    $('.datepicker').pickadate({
        labelMonthNext: 'Go to the next month',
        labelMonthPrev: 'Go to the previous month',
        labelMonthSelect: 'Pick a month from the dropdown',
        labelYearSelect: 'Pick a year from the dropdown',
        selectMonths: true,
        selectYears: true
    })

## Translations§

The picker can be extended to add support for internationalization. Translations for 39 languages are available out of the box, 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 languages that flow from right-to-left (RTL), 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 to the server.

This is done by creating a new hidden `input` element with the same `name` attribute as the original with 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'
    })

### Send the hidden `value` only§

A majority of the time, the value that needs to be sent to the server is just the hidden value – and not the visible one. To make this happen, use the `hiddenName` option.

This essentially nullifies the `hiddenPrefix` and `hiddenSuffix`, strips the `name` attribute from the source `input`, and then sets it as the `name` of the hidden `input`:

    $('.datepicker').pickadate({
        formatSubmit: 'yyyy/mm/dd',
        hiddenName: true
    })

### Pre-fill values using custom formats or translations§

When using a custom formatting rule for the `format` option or 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 from custom formats into various languages:

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

### Formatting Rules§

To use a formatting rule, make sure to keep a delimiter between each rule. This ensures each rule’s value can be parsed correctly. Example:
Bad: `yyyymmdd`; Good: `yyyy-mm-dd`.

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

* If you use the `yy` rule in the `format` option, you must specify the `yyyy` rule in the `formatSubmit` option with the appropriate `data-value` attribute to ensure the date parses accurately.

Never use the `yy` rule in the `formatSubmit` option.

## 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 values passed to the server will be of a consistent format.

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.

### Using HTML5 attributes§

Because each `input` is `readOnly` by default, HTML5 attributes, such as `required` and `pattern`, do not get enforced.

To enable default browser behavior on these attributes, set the `editable` property to `true`.

## Dropdown Selectors§

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

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

When `selectYears` is truthy, the year selector appears before the month. Read here for more details on why.

You can also specify the number of years to show in the dropdown 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.

### Using JavaScript dates§

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

### Using arrays formatted as `[YEAR,MONTH,DATE]`§

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

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

### Using JavaScript dates§

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

### Using arrays formatted as `[YEAR,MONTH,DATE]`§

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

### Using integers as days of the week (1 to 7)§

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

### Using objects as a range of dates§

    $('.datepicker').pickadate({
        disable: [
            { from: [2014,2,14], to: [2014,2,27] }
        ]
    })

The values for `from` & `to` can be:

- A JavaScript Date object,
- An array formatted as `[YEAR,MONTH,DATE]`,
- And `true` to set it as “today”.

The values can also be integers representing dates relative to the other:

- `to` can only be positive:

      { from: [2014,3,12], to: 10 }

- `from` can only be negative:

      { from: -10, to: true }

### Disabling all with a set of exceptions§

Enable only 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)
        ]
    })

### Disabling ranges with exceptions§

Enable dates that fall within a range of disabled dates by adding the `inverted` parameter to the item within the collection:

    $('.datepicker').pickadate({
        disable: [
            5,
            [2013, 10, 21, 'inverted'],
            { from: [2014, 3, 15], to: [2014, 3, 25] },
            [2014, 3, 20, 'inverted'],
            { from: [2014, 3, 17], to: [2014, 3, 18], inverted: true }
        ]
    })

## 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(context) {
            console.log('Just set stuff:', context)
        }
    })

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

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

To learn more on how to use the picker object, read the API documentation.