pickadate.js

A mobile-friendly, responsive, and lightweight jQuery dateinput picker
9.6kb min, 4.0kb gzipped

Fork me on GitHub

Download pickadate.js v2.1.7 (for old browsers) or view the themes

Jump to api documentation

§Default options

// 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' ],

// Display strings
monthPrev: '◀',
monthNext: '▶',
showMonthsFull: true,
showWeekdaysShort: true,

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

// Date formats
format: 'd mmmm, yyyy',
formatSubmit: false,
hiddenSuffix: '_submit',

// First day of week
firstDay: 0,

// Month & year dropdown selectors
monthSelector: false,
yearSelector: false,

// Date ranges
dateMin: false,
dateMax: false,

// Dates disabled
datesDisabled: false,

// Disable picker
disablePicker: false,

// Calendar events
onStart: null,
onOpen: null,
onClose: null,
onSelect: null,
onRender: null,

// Themes
klass: {
    active: 'pickadate__active',
    input: 'pickadate__input',

    // Picker holder states
    holder: 'pickadate__holder',
    opened: 'pickadate__holder--opened',
    focused: 'pickadate__holder--focused',

    // Picker frame and wrapper
    frame: 'pickadate__frame',
    wrap: 'pickadate__wrap',

    // Picker calendar
    calendar: 'pickadate__calendar',

    // Picker header
    header: 'pickadate__header',

    // Month navigation
    monthPrev: 'pickadate__nav--prev',
    monthNext: 'pickadate__nav--next',

    // Month & year labels
    month: 'pickadate__month',
    year: 'pickadate__year',

    // Select menus
    selectMonth: 'pickadate__select--month',
    selectYear: 'pickadate__select--year',

    // Picker table
    table: 'pickadate__table',

    // Weekday labels
    weekdays: 'pickadate__weekday',

    // Calendar body
    body: 'pickadate__body',

    // Day states
    day: 'pickadate__day',
    dayDisabled: 'pickadate__day--disabled',
    daySelected: 'pickadate__day--selected',
    dayHighlighted: 'pickadate__day--highlighted',
    dayToday: 'pickadate__day--today',
    dayInfocus: 'pickadate__day--infocus',
    dayOutfocus: 'pickadate__day--outfocus',

    // Footer
    footer: 'pickadate__footer',

    // Today and clear buttons
    buttonClear: 'pickadate__button--clear',
    buttonToday: 'pickadate__button--today'
}

§Simple setup

For the basic setup with the default options, invoke the picker on an input element. The type of the element doesn’t matter, but it must be an input element.

$( '.datepicker' ).pickadate()

A core behaviour is to give the input field a readonly attribute. This is done to prevent the keyboard from popping up on smartphones and also to maintain “pretty” dates that are simple to handle.

If you require the input to be editable, I would suggest using a date parsing library (such as datejs) along with the pickadate.js api to achieve this effect.

§Custom month and weekday tags

$( '.datepicker' ).pickadate({
    monthPrev: '←',
    monthNext: '→',
    weekdaysShort: [ 'Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa' ],
    showMonthsFull: false
})

§Today and clear buttons

As a default, today is set to 'Today' and clear is set to 'Clear'.

If either of the options is false, the button is not displayed.

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

For a custom “clear” button, check out the api for the clear method.

§Any language support

You can add support for any language in one of two ways.

(1) By passing the months and weekdays as an array for each invocation:

$( '.datepicker' ).pickadate({
    formatSubmit: 'dd/mm/yyyy',
    monthsFull: [ 'Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre' ],
    monthsShort: [ 'Jan', 'Fev', 'Mar', 'Avr', 'Mai', 'Juin', 'Juil', 'Aou', 'Sep', 'Oct', 'Nov', 'Dec' ],
    weekdaysShort: [ 'Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam' ],
    today: 'aujourd\'hui',
    clear: 'effacer'
})

(2) Or by globally extending the default picker options for all instances:

$.extend( $.fn.pickadate.defaults, {
    formatSubmit: 'dd/mm/yyyy',
    monthsFull: [ 'Janvier', 'Février', 'Mars', 'Avril', 'Mai', 'Juin', 'Juillet', 'Août', 'Septembre', 'Octobre', 'Novembre', 'Décembre' ],
    monthsShort: [ 'Jan', 'Fev', 'Mar', 'Avr', 'Mai', 'Juin', 'Juil', 'Aou', 'Sep', 'Oct', 'Nov', 'Dec' ],
    weekdaysShort: [ 'Dim', 'Lun', 'Mar', 'Mer', 'Jeu', 'Ven', 'Sam' ],
    today: 'aujourd\'hui',
    clear: 'effacer'
})

There are extensions for 28 languages already available.

The data-value attribute and formatSubmit option are both required to parse your dates correctly. Read more

§Custom date formats

$( '.datepicker' ).pickadate({
    format: 'You selected: dddd, dd mmm, yyyy',
    formatSubmit: 'yyyy/mm/dd'
})

Display human-friendly date formats while using a different format to submit to the server. Pick a date:

This is done by creating a hidden input field using the name attribute of the original input element plus the string set in the hiddenSuffix option.

As a default, hiddenSuffix is '_submit'.

The dates can be formatted using the following rules:

Rule Result Example
d Date 1-31
dd Date with leading zero 01-31
ddd Weekday – short Sun-Sat
dddd Weekday – full Sunday-Saturday
m Month 1-12
mm Month with leading zero 01-12
mmm Month name – short Jan-Dec
mmmm Month name – full January-December
yy Year – short * 00-99
yyyy Year – full 2000-2999

* The “short” year ( yy ) format is quite vague and should be avoided within formatSubmit so dates can be accurately parsed.

§Custom format parsing

If your input field has a custom date format or language that doesn't easily parse as a date, you can specify the date using the data-value attribute:

<input value="August 14" data-value="1988/08/14" class="datepicker" type="text">

The data-value attribute must be formatted using the formatSubmit option:

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

§Set Monday as the first day

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

Set firstDay to 1 for Monday and 0 for Sunday.

§Month and year dropdowns

$( '.datepicker' ).pickadate({
    monthSelector: true,
    yearSelector: true
})

If monthSelector or yearSelector is true, a select menu is displayed:

To change the number of years in the dropdown, set yearSelector as an even integer (half before the year in focus and half after). If set to true, it defaults to 10.

$( '.datepicker' ).pickadate({
    yearSelector: 4
})

§Minimum and maximum date range

$( '.datepicker' ).pickadate({
    dateMin: [ 2012, 10, 14 ],
    dateMax: 5
})

dateMin and dateMax can be either

  1. an array representing a date ([ yyyy, mm, dd ])
  2. a boolean (true or false)
  3. or an integer

If dateMax or dateMin is true, the range limit is set to today.

If dateMax or dateMin is false, the range limit is removed.

If dateMax or dateMin is an integer, it represents the relative number of days till the min or max date.

$( '.datepicker' ).pickadate({
    dateMin: -8,
    dateMax: true
})

§Disable arbitrary dates

Pass an array of arbitrary dates (each formatted as [ yyyy, mm, dd ]) to disable them.

$( '.datepicker' ).pickadate({
    datesDisabled: [
        [ 2013, 3, 2 ],
        [ 2013, 3, 5 ],
        [ 2013, 3, 28 ]
    ]
})

§Disable days of the week

Disable certain days of the week, such as all Saturdays (7th day of week) and Sundays (1st day of week), by passing an integer between 1 and 7:

$( '.datepicker' ).pickadate({
    datesDisabled: [
        1, 7,
        [ 2013, 3, 2 ],
        [ 2013, 3, 5 ],
        [ 2013, 3, 28 ]
    ]
})

§Disable all dates.. except some

Alternatively, disable all the dates in the calendar, except the ones specified if you set true as the first item in the array.

$( '.datepicker' ).pickadate({
    datesDisabled: [
        true,
        1, 7,
        [ 2013, 3, 2 ],
        [ 2013, 3, 5 ],
        [ 2013, 3, 28 ]
    ]
})

§Disable picker for native calendar

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

Some mobile browsers have good native support for type="date".

If you want to selectively disable the picker for these browsers, I would suggest detecing for support with something like Modernizr and then setting disablePicker to true.

§Do stuff on calendar events

$( '.datepicker' ).pickadate({
    onOpen: function() {
        console.log( 'Opened' )
    },
    onClose: function() {
        console.log( 'Closed' )
    },
    onSelect: function() {
        console.log( 'Selected: ' + this.getDate() )
    },
    onStart: function() {
        console.log( 'Hello there :)' )
    },
    onRender: function() {
      console.log( 'New calendar rendered!' )
    }
})

Have events trigger as the user interacts with the picker.

Within scope of these methods, this refers to the calendar picker. Open up your console and pick a date:

§api

There are 5 basic events in the options:

  1. onStart: invoked when the picker is initiated.
  2. onOpen: invoked when the picker is opened.
  3. onSelect: invoked when a date is selected or cleared.
  4. onClose: invoked when the picker is closed.
  5. onRender: invoked when the picker is rendered, including month changes.

Within the scope of these methods, this refers to the calendar object.

$( '.datepicker' ).pickadate({
    onStart: function() {
        var calendar = this
    }
})

Alternatively, you can grab the calendar object like this:

var input = $( '.datepicker' ).pickadate()
var calendar = input.data( 'pickadate' )

The following methods are available on the calendar object:

  1. open
  2. close
  3. isOpen
  4. show
  5. clear
  6. getDate
  7. setDate
  8. getDateLimit
  9. setDateLimit

You can also grab the jQuery object of the input element from the calendar like this:

this.$node

The $ prefix is used to signify a jQuery object.

§Open & close calendar

calendar.open()
calendar.close()

If you want to open the calendar on page load, you can add the autofocus attribute to the input element:

<input autofocus class="datepicker" type="text">

§Check if calendar is open

calendar.isOpen()

This method returns a true or false based on the state of the calendar.

§Show a specific month

calendar.show( month, year )

month and year have to be integers representing the month and year to show on the calendar.

year is optional. If none is specified, it shows the month of the year already in focus.

calendar.show( 4 )

This method does not open the calendar. However, the methods are chainable. So you can do this:

calendar.show( 10, 2015 ).open()

§Clear the date

calendar.clear()

Clears the selected date value from the input element.

With some custom stylings and api mastery, you can do something like this:

// Grab the clear button and bind the event
// to clear the input value on click
var clearButton = $( '#clearButton' ).on({ click: function() { inputElement.data( 'pickadate' ).clear() } }) // Grab the input element and trigger the picker
// with the onStart and onSelect methods to
// toggle the clear button visibility
var inputElement = $( '.datepicker' ).pickadate({ format: 'dd mmmm, yyyy', formatSubmit: 'yyyy-mm-dd', clear: false, onStart: showOrHideClear, onSelect: showOrHideClear }) // Check if the input element has a value
// and show or hide the button as needed
function showOrHideClear() { if ( this.$node.val() ) clearButton.show() else clearButton.hide() }
×

§Get the date

Get the date selected on the calendar:

calendar.getDate()

Optionally, you can pass a format in which you would like to get the date:

calendar.getDate( 'yyyy-mm-dd' )

To get the underlying JavaScript Date object, set format to true:

calendar.getDate( true )

§Set the date

calendar.setDate( year, month, date, superficial )

year, month, date are required integers representing the date to select on the calendar.

calendar.setDate( 2020, 2, 14 )

superficial is optional. If superficial is true, the date will only be superficially selected. This means the input value won't change.

calendar.setDate( 2020, 2, 14, true )

§Get the min or max date

calendar.getDateLimit( upper, format )

upper is optional. If upper is true, it returns the maximum date. Otherwise it gets the minimum date.

format is also optional. If none is specified, it falls back to the default format option in your invocation. Dates can be formatted with these rules.

calendar.getDateLimit()
calendar.getDateLimit( true, 'yyyy-mm-dd' )

§Set the min or max date

calendar.setDateLimit( date, upper )

date is a required array, integer, or boolean – similar to the dateMin and dateMax options in your invocation. This date is used to set the limit.

upper is optional. If upper is true, it will set the date as the maximum date selectable. Otherwise it sets it as the minimum date selectable.

calendar.setDateLimit( 40 )
calendar.setDateLimit( [ 2013, 6, 23 ], true )

§From & to calendars

Using the calendar API, you can create two calendars with a “from” and “to” interaction.

// When a date is selected on the "from" picker,
// get the date and split into an array.
// Then set the lower limit of the "to" picker.
var picker_from = $( '#picker_from' ).pickadate({ onSelect: function() { var fromDate = createDateArray( this.getDate( 'yyyy-mm-dd' ) ) picker_to.data( 'pickadate' ).setDateLimit( fromDate ) } }) // When a date is selected on the "to" picker,
// get the date and split into an array.
// Then set the upper limit of the "from" picker.
var picker_to = $( '#picker_to' ).pickadate({ onSelect: function() { var toDate = createDateArray( this.getDate( 'yyyy-mm-dd' ) ) picker_from.data( 'pickadate' ).setDateLimit( toDate, 1 ) } }) // Create an array from the date while parsing each date unit as an integer
function createDateArray( date ) { return date.split( '-' ).map(function( value ) { return +value }) }

Download pickadate.js v2.1.7

View calendar themes

Browser support: IE7+, Chrome, Firefox, Safari, Opera, iOS Safari, Android browser

Dependency: jQuery 1.7+

Note on browser support
The pickadate.js script supports IE 9+ by default. To support IE 7+ and other old browsers, use the pickadate.legacy.js script instead.

View project on Github

Featured on The Treehouse Show

Made by Amsul