jQuery Datepicker Reference

Datepicker Settings

A separate datepicker instance is created for each targetted control: $(selector).datepick();. When applied to a div or span the datepicker is rendered inline. Otherwise it appears as a popup on demand.

Each instance may have different settings, e.g.

$(selector).datepick({minDate: new Date()});

Alternately, you can specify the settings per control by including the jQuery Metadata plugin in your page and adding options to the class attribute, e.g.

<input type="text" class="{minDate: new Date()}"/>

The datepicker functionality can only be applied once. Affected controls are flagged with the hasDatepick class and are not re-processed if targetted again. Use the option command if you want to change settings after the initial setup.

Below are the settings that may be applied to each datepicker instance. All are optional.

A note on Date - the JavaScript Date constructor expects the year, month, and day as parameters. However, the month ranges from 0 to 11. To make explicit what date is intended (does a month of 3 mean March or April?) I specify the month from 1 to 12 and manually subtract the 1. Thus the following denotes 25 December, 2010.

$(selector).datepick({minDate: new Date(2010, 12-1, 25)});

alignment | altField | altFormat | autoSize | calculateWeek | changeMonth | commands | commandsAsDateFormat | constrainInput | defaultDate | fixedWeeks | maxDate | minDate | monthsOffset | monthsToJump | monthsToShow | monthsToStep | multiSelect | multiSeparator | onChangeMonthYear | onClose | onDate | onSelect | onShow | pickerClass | popupContainer | rangeSelect | rangeSeparator | selectDefaultDate | selectOtherMonths | shortYearCutoff | showAnim | showOnFocus | showOptions | showOtherMonths | showSpeed | showTrigger | useMouseWheel | yearRange

$(selector).datepick({pickerClass: 'my-picker'});

$(selector).datepick({showTrigger:
    '<img src="img/calendar.gif" alt="Popup" class="trigger">'});
$(selector).datepick({showTrigger: '#myicon'});

$(selector).datepick({showAnim: 'fadeIn'});
$(selector).datepick({showAnim: 'clip'});
$(selector).datepick({showAnim: ''}); // Immediate

$(selector).datepick({showAnim: 'clip',
    showOptions: {direction: 'horizontal'}});

$(selector).datepick({showSpeed: 'fast'});
$(selector).datepick({showSpeed: 1500});

$(selector).datepick({popupContainer: '#mydiv'});

$(selector).datepick({calculateWeek: myWeek,
    renderer: $.datepick.weekOfYearRenderer});
	
function myWeek(date) {
    return Math.floor(($.datepick.dayOfYear(date) - 1) / 7) + 1;
}

$(selector).datepick({monthsToShow: 3});
$(selector).datepick({monthsToShow: [2, 3]});

$(selector).datepick({
    monthsToShow: 3, monthsOffset: 1});

$(selector).datepick({yearRange: '1980:2000'});
$(selector).datepick({yearRange: '1960:-18'});
$(selector).datepick({yearRange: 'c+10:c-10'}); // Descending
$(selector).datepick({yearRange: 'any'});

$(selector).datepick({
    showOtherMonths: true, selectOtherMonths: true});

$(selector).datepick({
    defaultDate: new Date(2009, 1-1, 26)});
$(selector).datepick({defaultDate: '01/26/2009'});
$(selector).datepick({defaultDate: +7});
$(selector).datepick({defaultDate: '+1m -1d'});

$(selector).datepick({
    defaultDate: '01/26/2009', selectDefaultDate: true});

$(selector).datepick({
    minDate: new Date(2008, 12-1, 25)});
$(selector).datepick({minDate: '12/25/2008'});
$(selector).datepick({minDate: -10});
$(selector).datepick({minDate: '-1m -15d'});

$(selector).datepick({
    maxDate: new Date(2009, 12-1, 25)});
$(selector).datepick({maxDate: '12/25/2009'});
$(selector).datepick({maxDate: +10});
$(selector).datepick({maxDate: '+1m +15d'});

$(selector).datepick({
    onDate: function(date, current) {
        return !current ? {} :
			{content: date.getDate() + '<br><sub>' +
            $.datepick.dayOfYear(date) + '</sub>',
            dateClass: 'showDoY'};
    }
});

$(selector).datepick({
    onShow: function(picker, inst) {
        picker.find('td:even').addClass('alternate-dates');
    }
});

$(selector).datepick({
    onChangeMonthYear: function(year, month) {
        $('#monthYear').text(month + '/' + year);
    }
});

$(selector).datepick({
    onSelect: function(dates) {
        $('#count').text('Selected ' + dates.length + ' date(s)');
        var minDate = dates[0];
        for (var i = 1; i < dates.length; i++) {
            if (dates[i].getTime() < minDate.getTime()) {
                minDate = dates[i];
            }
        }
        $('#minDate').text($.datepick.formatDate(minDate));
    }
});

$(selector).datepick({
    onClose: function(dates) {
        var selected = '';
        for (var i = 0; i < dates.length; i++) {
            selected += ',' + $.datepick.formatDate(dates[i]);
        }
        alert('Selected dates are: ' + selected.substring(1));
    }
});

$(selector).datepick({dateFormat: 'DD, MM d, yyyy',
    altField: '#isoDate', altFormat: 'yyyy-mm-dd'});

$(selector).datepick({commandsAsDateFormat: true,
    prevText: '< M', todayText: 'M y', nextText: 'M >'});

Datepicker Commands

The datepicker contains a series of commands that operate upon it, allowing these to be customised or new commands added. Each command consists of an object with the attributes shown below, and is added to the commands setting. The standard commands are listed below.

Since 4.0.0.

Standard Commands

The standard commands defined by the datepicker are shown below and are available as $.datepick.commands. These may be positioned in the datepicker by including the '{link:name}' or '{button:name}' substitution points in the renderer values, where name is the command name below. Commands can be invoked on a datepicker with the performAction command.

Datepicker Localisation

These settings comprise the regional settings that may be localised by a language package. They can be overridden for individual instances:

$(selector).datepick({prevText: '<'});

clearStatus | clearText | closeStatus | closeText | currentStatus | currentText | dateFormat | dayNames | dayNamesMin | dayNamesShort | dayStatus | defaultStatus | firstDay | isRTL | monthNames | monthNamesShort | monthStatus | nextJumpStatus | nextJumpText | nextStatus | nextText | prevJumpStatus | prevJumpText | prevStatus | prevText | renderer | todayStatus | todayText | weekStatus | weekText | yearStatus

$(selector).datepick({dateFormat: 'yyyy-mm-dd'});
$(selector).datepick({dateFormat:
    '\'day\' d \'of\' MM \'in the year\' yyyy'});
$(selector).datepick({dateFormat: $.datepick.FULL});

$(selector).datepick({
    renderer: $.datepick.weekOfYearRenderer});
$(selector).datepick({
    renderer: $.extend({}, $.datepick.defaultRenderer,
        {picker: $.datepick.defaultRenderer.picker.
            replace(/\{link:clear\}/, '{button:clear}').
            replace(/\{link:close\}/, '{button:close}')})});

$(selector).datepick({
    prevText: '< M', commandsAsDateFormat: true});

$(selector).datepick({
    nextText: 'M >', commandsAsDateFormat: true});

Datepicker Renderers

Renderers allow you to use a templating mechanism to construct the datepicker for display. They are assigned to a datepicker instance as the renderer setting, one of the localisation settings.

Since 4.0.0.

You control the structure of the datepicker, the placement of controls within it, and the CSS styling that is applied to it. Substitution points of the form '{xxx}' indicate where standard content should be inserted.

There is a default renderer defined in the datepick module and several alternative renderers in the datepick.ext module. These are all described below.

If you define your own custom render it must contain all of the attributes described below. Alternatively you can tweak an existing renderer:

$(selector).datepick({renderer: $.extend(
    {}, $.datepick.defaultRenderer,
    {picker: $.datepick.defaultRenderer.picker.
        replace(/\{link:today\}/, '{link:current}')})});

commandButtonClass | commandClass | commandLinkClass | day | dayHeader | daySelector | defaultClass | disabledClass | highlightedClass | month | monthSelector | monthRow | multiClass | otherMonthClass | picker | rtlClass | selectedClass | todayClass | week | weekHeader | weekendClass

Standard Renderers

The standard renderers are listed below. Each is accessible within the $.datepick object via the given name.

Datepicker Globals

var altCommands = $.extend(true, {}, $.datepick.commands); // Clone
altCommands.prevJump.keystroke = {keyCode: 33, altKey: true}; // Alt+PageUp
altCommands.nextJump.keystroke = {keyCode: 34, altKey: true}; // Alt+PageDown

$('#keystrokePicker').datepick({commands: altCommands,
    showTrigger: '#myicon'});

<script type="text/javascript"
    src="jquery.datepick-fr.js"></script>

$.datepick.setDefaults($.datepick.regional['']);

$('#frenchDatepicker').datepick($.datepick.regional['fr']);

Functions and Commands

changeDay | changeMonth | clear | destroy | disable | enable | errorPlacement | getDate | hide | isDisabled | isSelectable | multipleEvents | option (get) | option (set) | performAction | retrieveDate | selectDate | setDate | setDefaults | show | showMonth

$.datepick.setDefaults({dateFormat: 'yyyy-mm-dd'});

$(selector).datepick('option', {firstDay: 1});

$(selector).datepick('option', 'firstDay', 1);

var settings = $(selector).datepick('option');
var firstDay = $(selector).datepick('option', 'firstDay');

var dates = $(selector).datepick('getDate');

$(selector).datepick('setDate', new Date(2009, 1-1, 26));
$(selector).datepick('setDate', '01/26/2009');
$(selector).datepick('setDate', '+1m'); // Today + 1 month
$(selector).datepick('setDate', 7); // Today + 7 days
$(selector).datepick('setDate',
    [new Date(2009, 1-1, 26), '+1m', 7]);

$(selector).datepick('setDate',
    new Date(2009, 1-1, 26), new Date(2010, 1-1, 26));
$(selector).datepick('setDate', 7, '+1m');

$(selector).datepick('performAction', 'today');

$(selector).datepick('showMonth', 2009, 1);

$(selector).datepick('changeMonth', -6);

$(selector).datepick('changeDay', -14);

$(selector).datepick({
    onShow: $.datepick.multipleEvents(
        $.datepick.changeFirstDay, $.datepick.showStatus)});

Datepicker Date Functions

There are a number of functions available on the $.datepick object to make it easier to work with dates.

add | day | dayOfYear | daysInMonth | determineDate | formatDate | iso8601Week | month | newDate | parseDate | today | year

var f = gc.formatDate('yyyy-mm-dd', date);
var f = gc.formatDate(
    '\'day\' d \'of\' MM \'in the year\' yyyy', date,
    {monthNames: ['1st month', '2nd month', ...]});

var date = gc.parseDate('yyyy-mm-dd', '2009-01-26');
var date = gc.parseDate(
    '\'day\' d \'of\' MM \'in the year\' yyyy',
    'day 26 of 1st month in the year 2009',
    {monthNames: ['1st month', '2nd month', ...]});

var date = gc.determineDate(+2);
var date = gc.determineDate('+2y -3w',
    gc.newDate(2001, 1, 1));
var date = gc.determineDate('2004-01-26',
    gc.newDate(2001, 1, 26), 'yyyy-mm-dd');

var dim = $.datepick.daysInMonth(2010, 1);
var dim = $.datepick.daysInMonth($.datepick.today());

var doy = $.datepick.dayOfYear(2010, 12, 25);
var doy = $.datepick.dayOfYear($.datepick.today());

var woy = $.datepick.iso8601Week(2010, 12, 25);
var woy = $.datepick.iso8601Week($.datepick.today());

var today = $.datepick.today();

var d = $.datepick.newDate(2010, 1, 26);
var d2 = $.datepick.newDate(d);

$.datepick.year(d, 2001);
var millenium = $.datepick.day($.datepick.month(
    $.datepick.year(d, 2001), 1), 1);

var dec = $.datepick.month(d, 12);

var first = $.datepick.day(d, 1);

$.datepick.add(d, 2, 'w');
$.datepick.add($.datepick.add(d, 1, 'm'), -1, 'd');

There are also several predefined date formats for the datepicker:

Datepicker Extensions

The functions shown below are available through the datepick.ext module. There are also several renderers available from this module.

changeFirstDay | highlightWeek | hoverCallback | monthNavigation | monthOnly | noWeekends | selectMonth | selectWeek | showStatus

$(selector).datepick({
    onDate: $.datepick.noWeekends});

$(selector).datepick({
    onShow: $.datepick.changeFirstDay});

$(selector).datepick({
    onShow: $.datepick.hoverCallback(showHover)});
	
function showHover(date, selectable) {
    $('#hoverOutput').text(
        (selectable ? $.datepick.formatDate(date) : null) || 'nothing');
}

$(selector).datepick({
    onShow: $.datepick.highlightWeek});

$(selector).datepick({
    onShow: $.datepick.monthOnly});

$(selector).datepick({
    onShow: $.datepick.showStatus});

$(selector).datepick({changeMonth: false,
    onShow: $.datepick.monthNavigation});

$(selector).datepick({rangeSelect: true,
    renderer: $.datepick.weekOfYearRenderer,
    onShow: $.datepick.selectWeek});

$(selector).datepick({rangeSelect: true,
    renderer: $.datepick.weekOfYearRenderer,
    onShow: $.datepick.selectMonth});

Validation Integration

The datepicker can be integrated with Jörn Zaefferer's validation plugin by adding the jquery.datepick.validation.js extension to your page.

Since 3.5.1.
Since 4.0.5 - combined validation rules into dpDate; previously there were also dpMinDate, dpMaxDate, and dpMinMaxDate, added dpCompareDate rule.

One new validation is defined (dpDate). It automatically handles date ranges (including checking that the start date is not after the end date) and multiple dates, checks against any minDate and/or maxDate settings, and calls any onDate callback to verify selectability. It may be added as a class to your datepicker fields, or may be defined in the validate settings.

A second validation rule (dpCompareDate) lets you compare one date field with another date. This rule must be specified in the rules section of the validate call and be provided with a parameter to indicate the required comparison and the target date. Specify the comparison with any of the following: 'equal', 'eq', 'same', 'notEqual', 'ne', 'notSame', 'lessThan', 'lt', 'before', 'greaterThan', 'gt', 'after', 'notLessThan', 'ge', 'notBefore', 'notGreaterThan', 'le', 'notAfter'. Specify the target date as either the actual date (as a string in the current date format or a Date object), as 'today', or as another datepicker field (as a jQuery selector, jQuery collection, or DOM element). The two parameters can be combined into one string (if the latter is a string), be given as items in an array, or be given as an object with a single attribute named for the comparison and with a value of the target.

$('form').validate({
	rules: {
		field1: {
			dpCompareDate: 'before 12/25/2010'
		},
		field2: {
			dpCompareDate: ['ne', new Date(2010, 12 - 1, 25)]
		},
		field3: {
			dpCompareDate: {notLessThan: '#otherField'}
		}
	});

There is also a custom errorPlacement function defined so that the error messages appear after any trigger button or icon (or before it if using a right-to-left localisation).

You can customise the error messages via the datepicker defaults: $.datepick.setDefaults({...}). The message fields are validateDate, validateDateMin, validateDateMax, validateDateMinMax, validateDateCompare, validateDateToday, validateDateOther, validateDateEQ, validateDateNE, validateDateLT, validateDateGT, validateDateLE, and validateDateGE. Within these messages '{n}' mark substitution points.

The sample page below show how the validations would be used. It defines three datepicker fields: one plain, one a date range, and one with a maximum limit. The validations are applied to the first and last by including the dpDate class on the fields. For the middle one the validation is defined in the validate call on the form, along with a required setting. Also note that a custom message is defined for the date range field.

<head>
<style type="text/css">@import "css/jquery.datepick.css";</style>
<script type="text/javascript" src="js/jquery-1.4.2.js"></script>
<script type="text/javascript" src="js/jquery.validate.js"></script>
<script type="text/javascript" src="js/jquery.datepick.js"></script>
<script type="text/javascript" src="js/jquery.datepick.validation.js"></script>
<script type="text/javascript">
$(function() {
	$('#favDate').datepick();
	$('#holidayDates').datepick({rangeSelect: true});
	$('#birthDate').datepick({maxDate: 0});

	$('#validateForm').validate({
		errorPlacement: $.datepick.errorPlacement,
		rules: {
			holidayDates: {
				required: true,
				dpDate: true
			}
		},
		messages: {
			holidayDates: 'Please enter a valid date range'
		}
	});
});
</script>
</head>
<body>
	<form id="validateForm">
		<p>Favourite date: <input type="text" id="favDate"
			name="favDate" size="10" class="dpDate"/></p>
		<p>Period of last holiday: <input type="text" id="holidayDates"
			name="holidayDates" size="24"/></p>
		<p>Date of birth: <input type="text" id="birthDate"
			name="birthDate" size="10" class="dpDate"/></p>
	</form>
</body>

Compatibility

Version 4.0.0 is a major update to the datepicker. As such, several compatibility issues arise when upgrading from version 3.7.x:

• dateFormat years have changed: use 'yy' for two digit year or 'yyyy' for four digit year.
• showOn, buttonText, buttonImage, and buttonImageOnly settings are replaced by showOnFocus and showTrigger settings.

  $(selector).datepick({showOn: 'button'});

  becomes

  $(selector).datepick({showOnFocus: false, showTrigger: '<button>...</button>'});

  and

  $(selector).datepick({showOn: 'both', buttonImage: 'img/mycal.gif', buttonImageOnly: true});

  becomes

  $(selector).datepick({showTrigger: '<img src="img/mycal.gif" alt="..."></img>'});

• duration setting is replaced by the showSpeed setting.
• numberOfMonths setting is replaced by the monthsToShow setting and showCurrentAtPos setting is replaced by the monthsOffset setting.
• stepMonths setting is replaced by the monthsToStep setting and stepBigMonths setting is replaced by the monthsToJump setting.
• changeYear setting is no longer available while the changeMonth setting now controls both drop-downs.
• showDefault setting is replaced by the selectDefaultDate setting.
• closeAtTop, gotoCurrent, mandatory, showBigPrevNext, and showMonthAfterYear settings are no longer available but the same functionality can be achieved with the renderer setting.
• hideIfNoPrevNext setting is no longer available but the same functionality can be achieved with the pickerClass setting and some CSS.
• navigationAsDateFormat setting is replaced by the commandsAsDateFormat setting.
• onClose and onSelect functions only receive an array of Date objects as a parameter.
• appendText setting is no longer available but the same functionality can be achieved using normal jQuery.
• useThemeRoller setting is no longer available but the same functionality can be achieved with the renderer setting and the themeRollerRenderer object in the extension module.

  $(selector).datepick({useThemeRoller: true});

  becomes

  $(selector).datepick({renderer: $.datepick.themeRollerRenderer});

• beforeShowDay setting is replaced by onDate setting and returns an object with attributes instead of an array.

  $(selector).datepick({beforeShowDay: highlightDays});
  
  function highlightDays(date) {
  	return [true, 'highlight', 'tooltip'];
  }

  becomes

  $(selector).datepick({onDate: highlightDays});
  
  function highlightDays(date) {
  	return {selectable: true, dateClass: 'highlight', title: 'tooltip'};
  }

• beforeShow setting is no longer available but similar functionality can be achieved by using the option command at an earlier time.
• changeFirstDay setting is no longer available but the same functionality can be achieved with the onShow setting and the changeFirstDay function in the extension module.

  $(selector).datepick({changeFirstDay: true});

  becomes

  $(selector).datepick({onShow: $.datepick.changeFirstDay});

• showWeeks setting is no longer available but the same functionality can be achieved with the renderer setting and the weekOfYearRenderer object in the extension module.

  $(selector).datepick({showWeeks: true});

  becomes

  $(selector).datepick({renderer: $.datepick.weekOfYearRenderer});

• highlightWeek setting is no longer available but the same functionality can be achieved with the onShow setting and the highlightWeek function in the extension module.

  $(selector).datepick({highlightWeek: true});

  becomes

  $(selector).datepick({onShow: $.datepick.highlightWeek});

• onHover setting is no longer available but the same functionality can be achieved with the onShow setting and the hoverCallback function in the extension module.

  $(selector).datepick({onHover: hoveringOver});

  becomes

  $(selector).datepick({onShow: $.datepick.hoverCallback(hoveringOver)});

• showStatus setting is no longer available but the same functionality can be achieved with the onShow setting and the showStatus function in the extension module.

  $(selector).datepick({showStatus: true});

  becomes

  $(selector).datepick({onShow: $.datepick.showStatus});

• Opening the datepicker in a dialog is no longer available but the same functionality can be achieved by combining the datepicker with the jQuery UI Dialog plugin.