jQuery UI API - Datepicker Widget

Category

Widgets

Usage

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

Version Added: 1.0

jQuery UI Datepicker is a highly configurable plugin that adds datepicker functionality to your pages. You can customize the date format and language, restrict the selectable date ranges, 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. Opens the datepicker if it is closed.
• 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 the option() method to change settings for individual instances.

Set all datepickers to open on focus or icon click.

$.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 combinations 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 day name
• DD - Long day name
• m - Month of the year (no leading zero)
• mm - Month of the year (two digits)
• M - Short month name
• MM - Long month name
• y - Year (two digits)
• yy - Year (four digits)
• @ - Unix timestamp (ms since 01/01/1970)
• ! - Windows ticks (100ns since 01/01/0001)
• '...' - Text
• '' - Single quote
• Other - Text

There are also predefined standard date formats in $.datepicker:

• 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)

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

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

Display the date in an 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)

Extracts 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 - Full 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 - Full name of the month
• y - Year (two digits)
• yy - Year (four digits)
• @ - Unix timestamp (ms since 01/01/1970)
• ! - Windows file time (100ns since 01/01/0001)
• '...' - Text
• '' - Single quote
• Other - Text

Some possible exceptions thrown:

• 'Invalid arguments' - Thrown if the format or value is empty.
• 'Missing number at position nn' - Thrown if a number expected by the format is not found.
• 'Unknown name at position nn' - Thrown if a day name or month name expected by the format is not found.
• 'Unexpected literal at position nn' - Thrown if a text value expected by the format is not found.
• 'Invalid date' - Thrown if the date is invalid, such as '31/02/2007'.

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", {
  shortYearCutoff: 20,
  dayNamesShort: $.datepicker.regional["fr"].dayNamesShort,
  dayNames: $.datepicker.regional["fr"].dayNames,
  monthNamesShort: $.datepicker.regional["fr"].monthNamesShort,
  monthNames: $.datepicker.regional["fr"].monthNames
});

$.datepicker.iso8601Week(date)

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

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

This function is the default implementation of the calculateWeek option.

Find the week of the year for a date.

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

$.datepicker.noWeekends

Sets a beforeShowDay function to prevent selection of weekends.

We can provide the noWeekends() function in the beforeShowDay option to calculate all weekdays, providing an array of true/false values to indicate whether a date is selectable.

Set the DatePicker to make weekends unselectable.

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

Limitations

The date picker provides support for localized content that caters to different languages and date formats. Each localization is contained in a file that appends a language code after the name, for example, French is `jquery.ui.datepicker-fr.js`. The required localization files should be included after the main date picker code. Each localization file adds its own settings to the available set of localizations, and all instances automatically apply these settings as defaults.

The `$.datepicker.regional` property holds an array of localizations, with the language code as a prefix, defaulting to `""` for English. Each entry is an object with the following properties: `closeText`, `prevText`, `nextText`, `currentText`, `monthNames`, `monthNamesShort`, `dayNames`, `dayNamesShort`, `dayNamesMin`, `weekHeader`, `dateFormat`, `firstDay`, `isRTL`, `showMonthAfterYear`, and `yearSuffix`.

You can restore the default localization with the following code:

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

### Theming

The Datepicker widget uses the [jQuery UI CSS Framework](api-css-framework.html) to define its appearance and style. If you need to use specific styles for the date picker, you can use the following CSS class names:

- `ui-datepicker`: The outer container of the date picker. If the date picker is inline, this element will also have a `ui-datepicker-inline` class. If the [isRTL](api-datepicker.html#option-isRTL) option is set, this element will also have a `ui-datepicker-rtl` class.

- `ui-datepicker-header`: The header container of the date picker.

- `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 date picker that includes the month and year.

- `ui-datepicker-month`: The text display of the month, or a `<select>` element if the [changeMonth](api-datepicker.html#option-changeMonth) option is set.

- `ui-datepicker-year`: The text display of the year, or a `<select>` element if the [changeYear](api-datepicker.html#option-changeYear) option is set.

- `ui-datepicker-calendar`: The table containing the calendar.

- `ui-datepicker-week-end`: The cells containing weekend days.

- `ui-datepicker-other-month`: The cells containing days that occur in a month but are not in the current month.

- `ui-datepicker-unselectable`: The cells that are not selectable by the user.

- `ui-datepicker-current-day`: The cell containing the selected date.

- `ui-datepicker-today`: The cell containing today's date.

- `ui-datepicker-buttonpane`: The button pane used when the [showButtonPanel](api-datepicker.html#option-showButtonPanel) option is set.

- `ui-datepicker-current`: The button for selecting today's date.

If the [numberOfMonths](api-datepicker.html#option-numberOfMonths) option is used to display multiple months, some additional classes are used:

- `ui-datepicker-multi`: The outermost container of a multi-month date picker. This element will also have a `ui-datepicker-multi-2`, `ui-datepicker-multi-3`, or `ui-datepicker-multi-4` class depending on the number of months displayed.

- `ui-datepicker-group`: The individual selectors within a group. This element will also have a `ui-datepicker-group-first`, `ui-datepicker-group-middle`, or `ui-datepicker-group-last` class depending on its position in the group.

### Dependencies

- [UI Core](ref-ui-core.html)
This is an English translation of the Chinese text.

- **[Effects Core](ref-effects-core.html)** (Optional; when used with the [showAnim](api-datepicker.html#option-showAnim) option)

### Additional Notes

- This widget requires some functional CSS to work properly. If you create a custom theme, use the widget-specific CSS file as a starting point.

- This widget manipulates the element's value programmatically, so the native `change` event will not be triggered when the element's value changes.

- Creating a datepicker on an `<input type="date">` is not supported, as it would cause conflicts with the native picker's UI.

## Example

A simple jQuery UI Datepicker.

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Datepicker Widget Demonstration</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>

View Demo