jQuery UI API - Datepicker Widget

Usage

Description:Select a date from a popup or inline calendar.

Version added:1.0

The jQuery UI Datepicker is a highly configurable plugin that adds date picker functionality to your pages. You can customize the date format and language, restrict the selectable date range, and add buttons and other navigation options.

By default, the datepicker opens in a small overlay when the associated text field gains focus. For an inline calendar, simply attach the datepicker to a div or span.

Keyboard interaction

When the datepicker is open, the following keyboard commands are available:

PAGE UP: Move to the previous month.
PAGE DOWN: Move to the next month.
CTRL+PAGE UP: Move to the previous year.
CTRL+PAGE DOWN: Move to the next year.
CTRL+HOME: Move to the current month. If the datepicker is closed, open it.
CTRL+LEFT: Move to the previous day.
CTRL+RIGHT: Move to the next day.
CTRL+UP: Move to the previous week.
CTRL+DOWN: Move to the next week.
ENTER: Select the focused date.
CTRL+END: Close the datepicker and clear the date.
ESCAPE: Close the datepicker without making a selection.

Utility Functions

$.datepicker.setDefaults( settings )

Change the default settings for all datepickers.

Use theoption()method to change the settings of individual instances.

Code examples:

Set all datepickers to open when they gain focus or when an icon is clicked.

$.datepicker.setDefaults({
  showOn: "both",
  buttonImageOnly: true,
  buttonImage: "calendar.gif",
  buttonText: "Calendar"
});

Set all datepickers to have French text.

$.datepicker.setDefaults( $.datepicker.regional[ "fr" ] );

$.datepicker.formatDate( format, date, settings )

Format a date into a string value with a specified format.

The format can be a combination of the following:

d - day of the month (no leading zero)
dd - day of the month (two digits)
o - day of the year (no leading zero)
oo - day of the year (three digits)
D - short name of the day
DD - long name of the day
m - month of the year (no leading zero)
mm - month of the year (two digits)
M - short name of the month
MM - long name of the month
y - year (two digits)
yy - year (four digits)
@ - Unix timestamp (ms since 01/01/1970)
! - Windows clock (100ns since 01/01/0001)
'...' - literal text
'' - single quote
Anything else - literal text

There are also some$.datepickerpredefined standard date formats:

ATOM - 'yy-mm-dd' (same as RFC 3339/ISO 8601)
COOKIE - 'D, dd M yy'
ISO_8601 - 'yy-mm-dd'
RFC_822 - 'D, d M y' (see RFC 822)
RFC_850 - 'DD, dd-M-y' (see RFC 850)
RFC_1036 - 'D, d M y' (see RFC 1036)
RFC_1123 - 'D, d M yy' (see RFC 1123)
RFC_2822 - 'D, d M yy' (see RFC 2822)
RSS - 'D, d M y' (same as RFC 822)
TICKS - '!'
TIMESTAMP - '@'
W3C - 'yy-mm-dd' (same as ISO 8601)

Code examples:

Display a date in ISO format. Produces "2007-01-26".

$.datepicker.formatDate( "yy-mm-dd", new Date( 2007, 1 - 1, 26 ) );

Display a date in extended French format. Produces "Samedi, Juillet 14, 2007".

$.datepicker.formatDate( "DD, MM d, yy", new Date( 2007, 7 - 1, 14 ), {
  dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
  dayNames: $.datepicker.regional[ "fr" ].dayNames,
  monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
  monthNames: $.datepicker.regional[ "fr" ].monthNames
});

$.datepicker.parseDate( format, value, settings )

Extract a date from a string value with a specified format.

The format can be a combination of the following:

d - day of the month (no leading zero)
dd - day of the month (two digits)
o - day of the year (no leading zero)
oo - day of the year (three digits)
D - short name of the day of the week
DD - long name of the day of the week
m - month of the year (no leading zero)
mm - month of the year (two digits)
M - short name of the month
MM - long name of the month
y - year (two digits)
yy - year (four digits)
@ - Unix timestamp (ms since 01/01/1970)
! - Windows clock (100ns since 01/01/0001)
'...' - literal text
'' - single quote
Anything else - literal text

Some exceptions that may be thrown:

'Invalid arguments' - thrown if the format or value is empty.
'Missing number at position nn' - thrown if the format indicates a number that is not found.
'Unknown name at position nn' - thrown if the format indicates a day-of-week or month name that is not found.
'Unexpected literal at position nn' - thrown if the format indicates a literal value that is not found.
'Invalid date' - thrown if the date is invalid, such as '31/02/2007'.

Code examples:

Extract a date in ISO format.

$.datepicker.parseDate( "yy-mm-dd", "2007-01-26" );

Extract a date in extended French format.

$.datepicker.parseDate( "DD, MM d, yy", "Samedi, Juillet 14, 2007", {
  shortYearCuroff: 20,
  dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
  dayNames: $.datepicker.regional[ "fr" ].dayNames,
  monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
  monthNames: $.datepicker.regional[ "fr" ].monthNames
});

$.datepicker.iso8601Week( date )

Determine the week of the year for a given date: 1 to 53.

This function uses the ISO 8601 definition of a week: a week starts on Monday, and the first week of each year contains January 4. This means that at most three days from the previous year may be included in the first week of the current year, and at most three days from the current year may be included in the last week of the previous year.

This function is thecalculateWeekdefault implementation of the option.

Code examples:

Find the week of the year for a date.

$.datepicker.iso8601Week( new Date( 2007, 1 - 1, 26 ) );

$.datepicker.noWeekends

Set a function such as beforeShowDay to prevent selecting weekends.

We canbeforeShowDayprovide in the optionnoWeekends()a function to calculate all working days, providing antrue/falsearray of values to indicate whether the date is selectable.

Code examples:

Set the Datepicker so that weekends are not selectable.

$( "#datepicker" ).datepicker({
  beforeShowDay: $.datepicker.noWeekends
});

Limitations

The datepicker provides support for localizing content to suit different languages and date formats. Each localization is contained in a file with the language code appended to the name, for example, French isjquery.ui.datepicker-fr.js. The required localization file needs to be included after the main datepicker code. Each localization file adds its own settings to the available localization collection, and all instances automatically apply these settings as defaults.

$.datepicker.regionalThe property holds an array of localizations, keyed by language code, with the default key being"", which represents English. Each entry is an object with the following properties:closeText、prevText、nextText、currentText、monthNames、monthNamesShort、dayNames、dayNamesShort、dayNamesMin、weekHeader、dateFormat、firstDay、isRTL、showMonthAfterYearandyearSuffix。

You can restore the default localization with the following code:

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

You can override the datepicker for a specific locale with the following code:

$( selector ).datepicker( $.datepicker.regional[ "fr" ] );

Theming

The Datepicker Widget uses thejQuery UI CSS Frameworkto define its look and feel. If you need to use datepicker-specific styles, you can use the following CSS class names:

ui-datepicker: The outer container of the datepicker. If the datepicker is inline, this element will additionally have aui-datepicker-inlineclass. If setisRTLoption, this element will additionally have aui-datepicker-rtl class。
- ui-datepicker-header: The header container of the datepicker.
  - ui-datepicker-prev: The control for selecting the previous month.
  - ui-datepicker-next: The control for selecting the next month.
  - ui-datepicker-title: The title container of the datepicker containing the month and year.
    - ui-datepicker-month: The text display of the month. If thechangeMonthoption is set, it displays a<select>element.
    - ui-datepicker-year: The text display of the year. If thechangeYearoption is set, it displays a<select>element.
- ui-datepicker-calendar: The table containing the calendar.
  - ui-datepicker-week-end: Cells containing weekend days.
  - ui-datepicker-other-month: Cells for days that occur in a month but are not days of the current month.
  - ui-datepicker-unselectable: Cells that cannot be selected by the user.
  - ui-datepicker-current-day: Cells for the selected date.
  - ui-datepicker-today: Cells for the current date.
- ui-datepicker-buttonpane: When theshowButtonPaneloption is used, a button pane is used.
  - ui-datepicker-current: The button used to select the current date.

If thenumberOfMonthsoption is used to display multiple months, some additional classes are used:

ui-datepicker-multi: The outermost container of a multi-month datepicker. This element will additionally have aui-datepicker-multi-2、ui-datepicker-multi-3orui-datepicker-multi-4class name based on the number of months displayed.
- ui-datepicker-group: The individual picker within the group. This element will additionally have aui-datepicker-group-first、ui-datepicker-group-middleorui-datepicker-group-lastclass name based on its position in the group.

Dependencies

UI Core
Effects Core(optional; when used with theshowAnimoption)

Additional Notes

This widget requires some functional CSS, otherwise it will not work. If you create a custom theme, use the widget-specific CSS file as a starting point.
This widget manipulates the value of an element programmatically, so the nativechangeevent will not be triggered when the value changes.
: Not supported on<input type="date">: creating a Datepicker, because it will cause UI conflicts with the native picker.

Examples

A simple jQuery UI Datepicker.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>日期选择器部件（Datepicker Widget）演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
 
<div id="datepicker"></div>
 
<script>
$( "#datepicker" ).datepicker();
</script>
 
</body>
</html>

Other extensions

jQuery UI Theme

jQuery UI Component library

jQuery UI Reference Manual

jQuery UI Instance

jQuery UI API - Datepicker Widget

Category

Usage

Keyboard interaction

Utility Functions

$.datepicker.setDefaults( settings )

$.datepicker.formatDate( format, date, settings )

$.datepicker.parseDate( format, value, settings )

$.datepicker.iso8601Week( date )

$.datepicker.noWeekends

Limitations

Theming

Dependencies

Additional Notes

Examples