YouTip

# jQuery UI API – Datepicker Widget ## Category (#) ## Usage **Description:** Select a date from a popup or inline calendar. **Added in version:** 1.0 The 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 dates, 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 selection. ### Utility Functions #### $.datepicker.setDefaults( settings ) Change the default settings for all datepickers. Use the [`option()`](#) method to change settings for individual instances. **Code Example:** Set all datepickers to open on focus or on the icon. ```javascript $.datepicker.setDefaults({ showOn: "both", buttonImageOnly: true, buttonImage: "calendar.gif", buttonText: "Calendar"}); Set all datepickers to have French text. ```javascript $.datepicker.setDefaults( $.datepicker.regional ); #### $.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 digit) * o - Day of the year (no leading zero) * oo - Day of the year (three digit) * 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 digit) * M - Short name of the month * MM - Long name of the month * y - Year (two digit) * yy - Year (four digit) * @ - Unix Timestamp (ms since 01/01/1970) * ! - Windows Ticks (100ns since 01/01/0001) * '...' - Literal text * '' - Single quote * other - Literal text There are also some standard date formats predefined 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) **Code Example:** Display the date in ISO format. Produces "2007-01-26". ```javascript $.datepicker.formatDate( "yy-mm-dd", new Date( 2007, 1 - 1, 26 ) ); Display the date in extended French format. Produces "Samedi, Juillet 14, 2007". ```javascript $.datepicker.formatDate( "DD, MM d, yy", new Date( 2007, 7 - 1, 14 ), { dayNamesShort: $.datepicker.regional.dayNamesShort, dayNames: $.datepicker.regional.dayNames, monthNamesShort: $.datepicker.regional.monthNamesShort, monthNames: $.datepicker.regional.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 digit) * o - Day of the year (no leading zero) * oo - Day of the year (three digit) * 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 digit) * M - Short name of the month * MM - Long name of the month * y - Year (two digit) * yy - Year (four digit) * @ - Unix Timestamp (ms since 01/01/1970) * ! - Windows Ticks (100ns since 01/01/0001) * '...' - Literal text * '' - Single quote * other - Literal text Some possible 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 numeric value that is not found. * 'Unknown name at position nn' - Thrown if the format indicates a day or month name that is not found. * 'Unexpected literal at position nn' - Thrown if the format indicates a literal text value that is not found. * 'Invalid date' - Thrown if the date is invalid, e.g., '31/02/2007'. **Code Example:** Extract a date in ISO format. ```javascript $.datepicker.parseDate( "yy-mm-dd", "2007-01-26" ); Extract a date in extended French format. ```javascript $.datepicker.parseDate( "DD, MM d, yy", "Samedi, Juillet 14, 2007", { shortYearCuroff: 20, dayNamesShort: $.datepicker.regional.dayNamesShort, dayNames: $.datepicker.regional.dayNames, monthNamesShort: $.datepicker.regional.monthNamesShort, monthNames: $.datepicker.regional.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: weeks start on Monday, and the first week of the year contains January 4. 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 for the [`calculateWeek`](#) option. **Code Example:** Find the week of the year for a date. ```javascript $.datepicker.iso8601Week( new Date( 2007, 1 - 1, 26 ) ); #### $.datepicker.noWeekends Set as the `beforeShowDay` function to prevent selection of weekends. We can provide the `noWeekends()` function in the [`beforeShowDay`](#) option to calculate all weekdays, returning an array with a `true`/`false` value indicating whether the date is selectable. **Code Example:** Set the Datepicker to make weekends unselectable. ```javascript $( "#datepicker" ).datepicker({ beforeShowDay: $.datepicker.noWeekends }); ### Localization The datepicker provides support for localizing content to cater for different languages and date formats. Each localization is contained in a file with the language code appended to the name, e.g., `jquery.ui.datepicker-fr.js` for French. The required localization file must be included after the main datepicker code. Each localization file adds its own settings to the available localizations set, which are automatically applied as defaults to all instances. The `$.datepicker.regional` property holds an array of localizations, keyed by language code, with the default key `""` representing 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: ```javascript $.datepicker.setDefaults( $.datepicker.regional ); You can override a specific locale's datepicker with the following code: ```javascript $( selector ).datepicker( $.datepicker.regional ); ### Theming The Datepicker Widget uses the (#) to define its look and feel styling. If you need to use datepicker-specific styles, you can use the following CSS class names: * `ui-datepicker`: The outer container for the datepicker. If the datepicker is inline, this element will additionally have a `ui-datepicker-inline` class. If the [`isRTL`](#) option is set, this element will additionally have a `ui-datepicker-rtl` class. * `ui-datepicker-header`: The header container for the datepicker. * `ui-datepicker-prev`: The control to select the previous month. * `ui-datepicker-next`: The control to select the next month. * `ui-datepicker-title`: The title container for the month and year in the datepicker. * `ui-datepicker-month`: The text display for the month, or a `` element if the [`changeMonth`](#) option is set. * `ui-datepicker-year`: The text display for the year, or a `` element if the [`changeYear`](#) option is set. * `ui-datepicker-calendar`: The table containing the calendar. * `ui-datepicker-week-end`: Cells containing weekend days. * `ui-datepicker-other-month`: Cells containing days from other months. * `ui-datepicker-unselectable`: 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 when the [`showButtonPanel`](#) option is set. * `ui-datepicker-current`: The button to select today's date. If the [`numberOfMonths`](#) option is used to display multiple months, some additional classes are used: * `ui-datepicker-multi`: The outermost container for a multi-month datepicker. This element will additionally have `ui-datepicker-multi-2`, `ui-datepicker-multi-3`, or `ui-datepicker-multi-4` class names, depending on the number of months to display. * `ui-datepicker-group`: An individual selector within a group. This element will additionally have `ui-datepicker-group-first`, `ui-datepicker-group-middle`, or `ui-datepicker-group-last` class names, depending on its position within the group. ### Dependencies (Optional; used with the [`showAnim`](#) option) ### 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 element's value programmatically, so the native `change` event is not triggered when the element's value changes. * Creating a datepicker on an `` is not supported, as it would conflict with the native picker's UI. ## Example A simple jQuery UI Datepicker. $( "#datepicker" ).datepicker();