Defaults

A date picker can easily be added to an input field with default settings.

Default date picker:

IE select issue: Show how the date picker covers a select in IE

The defaults are:

• Date picker appears on focus
• Text is in English
• Date format is mm/dd/yyyy
• Clear/Close controls show at the top
• Month and year are selectable directly
• 10 years before and after the selected year are shown
• Show a single month
• Select a single date
• Week starts on Sunday
• Day names are clickable to change the first day of the week
• Days in other months are not displayed
• No date restrictions
• Clicking elsewhere closes the date picker

Processed fields are marked with a class of hasDatepicker and are not re-processed if targetted a second time.

You can override the default settings that apply to all date picker instances.

Invocation

The date picker can be invoked in a variety of ways, as shown below. Also shown is the use of an image only trigger, and how the controls and buttons appear when disabled.

Datepicker appears on focus:

Appears via text button:

Appears both ways:

You can embed the trigger image within the input area via CSS.

Embedded button:

Enable and disable datepicker with 'enable' and 'disable' commands.

The date picker can also be triggered externally for a particular input.

External trigger: Open date picker

Or even opened as a "dialog". If the blockUI plugin is available, it is used to create a modal dialog.

Date picker dialog: Open dialog

Keystrokes

The date picker also responds to keystrokes entered in the input field.

Keyboard driven:

The relevant keystrokes are:

• page up/downprevious/next month
• ctrl+page up/downprevious/next year
• ctrl+homecurrent month or open when closed
• ctrl+left/rightprevious/next day
• ctrl+up/downprevious/next week
• enteraccept the selected date
• ctrl+endclose and erase the date
• escapeclose the date picker without selection

Restricting

You can restrict the functionality of the date picker in various ways. The first example sets the first day of the week to Monday and prevents it from being changed, as well as preventing the month and year from being selected directly.

Restricted functionality:

You can also limit the range of dates selectable within the date picker. Here it's between 26-Jan-05 and 26-Jan-07.

Limited dates:

Or set a range relative to today by specifying a number rather than an exact date, in this case in the coming year.

Limited dates (relative):

The relative dates can also be specified as a number and a period - 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.

Limited dates (extended):

Note that the range of selectable months and years changes appropriately. Also, note that the Today link is no longer available as today is not in the range. By default, the Prev and Next links are disabled if they are not applicable. You can override this to remove them instead, with the hideIfNoPrevNext setting.

Date Formats

You can set a variety of date formats for the date picker, with the default being 'mm/dd/yy'.

Medium format:

Long format:

Full format:

Display dates without the century. The century is then determined based on the shortYearCutoff setting, which defaults to 10 years in the future ('+10'). Year values less than or equal to this cutoff are interpreted as being in the current century, while those greater than the cutoff are taken to be in the previous century.

No century:

ISO date format:

French full format:

The formatting codes are:

• dday of month (no leading zero)
• ddday of month (two digit)
• Dday name short
• DDday name long
• mmonth of year (no leading zero)
• mmmonth of year (two digit)
• Mmonth name short
• MMmonth name long
• yyear (two digit)
• yyyear (four digit)
• '...'literal text
• ''single quote

Customize

You can customize the selectability and/or appearance of individual days by setting a callback function that accepts a date and returns an array with the first entry being true/false for selectability and the second entry being a CSS class to apply (or '' for none). One appropriate function is built-in that prevents the selection of days on weekends.

No weekends:

Or you can provide your own function. The one below highlights and prevents selection of a set of national days.

National days:

With CSS like the following:

.au_day { color: blue !important; background: #eee url(au.gif) no-repeat center !important; }

Localisation

You can localise the date picker for other languages and regional differences. The date picker defaults to English with a date format of MM/DD/YYYY, but you can easily translate the text into another language and date format.

简体中文 (Chinese Simplified) 簡體中文 (Chinese Traditional) български език (Bulgarian) Català (Catalan) Čeština (Czech) Dansk (Danish) Deutsch (German) Español (Spanish) Français (French) 한국어 (Korean) Íslenska (Icelandic) Italiano (Italian) Magyar (Hungarian) Nederlands (Dutch) 日本語 (Japanese) lietuvių kalba (Lithuanian) Norsk (Norwegian) Phasa thai (Thai) Polski (Polish) Português (Portuguese) Română (Romanian) Русский (Russian) Slovenčina (Slovak) suomi (Finnish) Svenska (Swedish) Türkçe (Turkish) :

The presentation is slightly different for right-to-left languages.

עברית (Hebrew) :

You need to load the appropriate language package, which adds a language set ($.datepicker.regional[langCode]) and automatically sets this language as the default for all date pickers.

<script type="text/javascript" src="ui.datepicker-fr.js"></script>

Thereafter, if desired, you can restore the original language settings.

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

And then configure the language per date picker instance.

Localisation packages:

Localisation packages can be found below under Settings and Documentation.

Date Range

Use a custom field settings function to create a date range control: two date fields, each restricting the other. The function takes an input field as an argument and returns a settings object (anonymous).

Date range: to

Select a date range on one date picker, first click is the start date and second click is the end date. The last example show six months in two rows of three months with Previous and Next moving three months at a time.

Date range:

Two months with range select:

Six months with range select:

Miscellaneous 1

Set the date shown when first opening the date picker. The default is today.

Open at 01-Jan-2007:

Open at 7 days from today:

Or specify a period from today - 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.

Open at 2 weeks from today:

Show the weeks of the year. Defaults to the ISO 8601 definition (weeks start on Mondays and the first week of the year contains January 4). Change the week calculation by setting calculateWeek to a function that takes a date as a parameter and returns the number of the week.

Show week of the year:

Additional settings let you move the Clear/Close controls to the bottom, hide the Clear control to make the date mandatory, display the days in other months (non-selectable), and show a status bar (with a custom display for today). Callback functions are also added to operate when a date is selected and when the datepicker is closed. If no onSelect callback is specified, the onchange event of the input field is triggered.

Additional settings:

Miscellaneous 2

Hide the datepicker on demand (press alt-h here) or remove the datepicker altogether if you've finished with it.

Remove popup datepicker:   Remove

Remove inline datepicker:

(Advanced Technique)
Connect the date picker to linked drop-downs. You still need an input field, but it is hidden following the drop-downs.

Linked drop-downs: JanFeb MarApr MayJun JulAug SepOct NovDec 12 34 56 78 910 1112 1314 1516 1718 1920 2122 2324 2526 2728 2930 31 20012002 20032004 20052006 20072008 20092010

Changing Settings

If necessary, the datepicker settings for an input (or set of inputs) can be changed on the fly. As an example, here we change the animation and speed at which the datepicker appears.

Display animation and speed: show fade in slide down immediate slow medium fast

Change datepicker:

When the option in the select changes, the following function is called:

Date pickers can also be configured inline. Add attributes to the input control with the namespace "date:" corresponding to the date picker properties. The attribute values are evaluated as JavaScript.

Inline configuration 1: blank

Inline configuration 2:

Inline

The date picker can be used inline rather than as a popup. Use inline mode by attaching the datepicker to a span or div element.

Show a number of months at once and set the range directly.

Inline range with two months:

Selected range is:  

(Advanced Technique)
Set initial value of inline date range to one week before and after today's date. Set the text field to current selected date.

Set Inline Range to +and- one week

Stylesheets

The date picker can be formatted through the use of a stylesheet. The default stylesheet is used in the rest of this demo with an alternate one used here.

Alternate style:

In a dialog: Open dialog

The basic HTML structure of the date picker is shown below:

<div id="datepicker_div" class="datepicker_multi">
  <div class="datepicker_control">
    <div class="datepicker_clear"><a>Clear</a></div>
    <div class="datepicker_close"><a>Close</a></div>
  </div>
  <div class="datepicker_links">
    <div class="datepicker_prev"><a>&lt;Prev</a></div>
    <div class="datepicker_current"><a>Today</a></div>
    <div class="datepicker_next"><a>Next&gt;</a></div>
  </div>
  <div class="datepicker_oneMonth datepicker_newRow">
    <div class="datepicker_header">
      <select class="datepicker_newMonth"></select>
      <select class="datepicker_newYear"></select>
    </div>
    <table class="datepicker" cellpadding="0" cellspacing="0">
      <thead>
        <tr class="datepicker_titleRow">
          <td><a>Su</a></td><td><a>Mo</a></td>...
        </tr>
      </thead>
      <tbody>
        <tr class="datepicker_daysRow">
          <td class="datepicker_daysCell datepicker_weekEndCell
            datepicker_otherMonth datepicker_unselectable">31</td>
          <td class="datepicker_daysCell"><a>1</a></td>
          <td class="datepicker_daysCell datepicker_daysCellOver"><a>2</a></td>
          <td class="datepicker_daysCell datepicker_daysCellOver datepicker_currentDay"><a>3</a></td>
          <td class="datepicker_daysCell datepicker_today"><a>4</a></td>
          ...
        </tr>
        ...
      </tbody>
    </table>
  </div>
  <div class="datepicker_oneMonth">
    ...
  </div>
  <div style="clear: both;"></div>
</div>

Compatibility

v3.3 to v3.4

The jQuery UI interfaces changed again, so here's another compatibility module.

Users of v3.3 of the datepicker should use the following header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
<script type="text/javascript" src="ui.datepicker.js"></script>
<script type="text/javascript" src="ui.datepicker.compatibility-3.3.js"></script>

Download the ui.datepicker.compatibility-3.3.js module.

To migrate fully, the following steps need to be taken:

• Replace references to the $(selector).attachDatepicker(...) function with $(selector).datepicker(...).
• Replace references to the $(selector).removeDatepicker() function with $(selector).datepicker('destroy').
• Replace references to the $(selector).datepicker.changDatepicker(...) function with $(selector).datepicker('change', ...).
• Replace references to the $(selector).datepicker.enableDatepicker() function with $(selector).datepicker('enable').
• Replace references to the $(selector).disableDatepicker() function with $(selector).datepicker('disable').
• Replace references to the $(selector).isDisabledDatepicker() function with $(selector).datepicker('isDisabled').
• Replace references to the $(selector).showDatepicker() function with $(selector).datepicker('show').
• Replace references to the $.datepicker.hideDatepicker() function with $(selector).datepicker('hide').
• Replace references to the $(selector).getDatepickerDate() function with $(selector).datepicker('getDate').
• Replace references to the $(selector).setDatepickerDate(...) function with $(selector).datepicker('setDate', ...).

For example, this old style code:

$('inputs').attachDatepicker(...);
$('inputs').changeDatepicker(...);

becomes:

$('inputs').datepicker(...);
$('inputs').datepicker('change', ...);

v3.2 to v3.4

To align the datepicker more closely with other jQuery UI components, further changes were made in v3.3, resulting in another compatibility module.

Users of v3.2 of the datepicker should use the following header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
<script type="text/javascript" src="ui.datepicker.js"></script>
<script type="text/javascript" src="ui.datepicker.compatibility-3.2.js"></script>

Download the ui.datepicker.compatibility-3.2.js module.

To migrate fully, the following steps need to be taken:

• Replace references to the $.datepicker.reconfigureFor(selector, ...) function with $(selector).datepicker('change', ...).
• Replace references to the $.datepicker.enableFor(selector) function with $(selector).datepicker('enable').
• Replace references to the $.datepicker.disableFor(selector) function with $(selector).datepicker('disable').
• Replace references to the $.datepicker.isDisabled(selector) function with $(selector).datepicker('isDisabled').
• Replace references to the $.datepicker.showFor(selector) function with $(selector).datepicker('show').
• Replace references to the $.datepicker.getDateFor(selector) function with $(selector).datepicker('getDate').
• Replace references to the $.datepicker.setDateFor(selector, ...) function with $(selector).datepicker('setDate', ...).

For example, this old style code:

$.datepicker.reconfigureFor('inputs', {...});

becomes:

$('inputs').datepicker('change', {...});

v2.x to v3.3

The date picker has been refactored to better fit within the jQuery UI project. This has involved renaming the main function and some properties, resulting in current uses of the plugin no longer functioning correctly. To assist in the transition to the new format a compatibility plugin is also provided, allowing current code to continue to operate with minimal changes.

Existing users of v2 of the calendar should use the following header code to work with their existing implementation:

<link rel="stylesheet" type="text/css" href="ui.datepicker.css"/>
<script type="text/javascript" src="ui.datepicker.js"></script>
<script type="text/javascript" src="jquery-calendar-compatibility.js"></script>

Download the jquery-calendar-compatibility.js module.

To migrate fully, the following steps need to be taken:

• Replace references to the jquery-calendar* files with ui.datepicker*.
• Replace references to the popUpCal object with $.datepicker.
• Replace references to the calendar function with datepicker.
• Replace references to the autoPopUp setting with showOn.
• Replace references to the fieldSettings setting with beforeShow.
• Replace references to the customDate setting with beforeShowDay.
• Replace references to inline attributes with the cal: namespace with date:.
• Replace references to the hideCalendar function with hideDatepicker.
• Replace references to the dialogCalendar function with dialogDatepicker.
• Replace references to the $.datepicker.reconfigureFor(selector, ...) function with $(selector).datepicker('change', ...).
• Replace references to the $.datepicker.enableFor(selector) function with $(selector).datepicker('enable').
• Replace references to the $.datepicker.disableFor(selector) function with $(selector).datepicker('disable').
• Replace references to the $.datepicker.showFor(selector) function with $(selector).datepicker('show').
• Replace references to the $.datepicker.getDateFor(selector) function with $(selector).datepicker('getDate').
• Replace references to the $.datepicker.setDateFor(selector, ...) function with $(selector).datepicker('setDate', ...).
• Replace references to the calendar* CSS styles with datepicker*.

For example, this old style code:

$('inputs').calendar({autoPopUp: 'both', fieldSettings: setDateRange,
	customDate: popUpCal.noWeekends});
	
<input type="text" id="inlineConfig" cal:defaultDate="+7"/>

becomes:

$('inputs').datepicker({showOn: 'both', beforeShow: setDateRange,
	beforeShowDay: $.datepicker.noWeekends});
	
<input type="text" id="inlineConfig" date:defaultDate="+7"/>