Date pickers

Ask a question

Summary

A simple date picker polyfill for browsers that don't support date fields. Based on the jQuery UI Date Picker.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-date-picker
AMD Module key: N/A
Experimental API: 4
General API: 5.1

Code

HTML & JavaScript

The AUI Date Picker is set up with an HTML5 date input, plus JavaScript to set the desired options. In most implementations Date Picker is set to override the native implementation at all times. This gives a consistent experience in all browsers.

Options

Options are set in the JavaScript options object:

Option Type Default Effect
overrideBrowserDefault Boolean false Provides the polyfill regardless of whether or not the browser supports date input fields. If the browser supports date input fields, the field type is changed totext to suppress the browser's native date picker implementation. 

Use this option to maintain a consistent look across browsers, especially when native implementations are aesthetically unpleasant (as with Opera) or incomplete (as with Safari's spinner-only implementation).
firstDay Number -1 Sets the starting day of the calendar week. Zero to six represents Sunday to Saturday, and -1 represents the localisation's default setting.
languageCode String The html element's lang attribute if available, otherwise en-AU.

Localises various aspects of the date picker, including day names, the first day of the week, RTL text, month names, whether the year precedes the month, and whether the year requires a suffix. 

The following locales are supported: '' (used when an unavailable language code is specified), 'af', 'ar-DZ', 'ar', 'az', 'bg', 'bs', 'ca', 'cs', 'da', 'de', 'el', 'en-AU', 'en-GB', 'en-NZ', 'eo', 'es', 'et', 'eu', 'fa', 'fi', 'fo', 'fr-CH', 'fr', 'gl', 'he', 'hr', 'hu', 'hy', 'id', 'is', 'it', 'ja', 'ko', 'kz', 'lt', 'lv', 'ml', 'ms', 'nl', 'no', 'pl', 'pt-BR', 'pt', 'rm', 'ro', 'ru', 'sk', 'sl', 'sq', 'sr-SR', 'sr', 'sv', 'ta', 'th', 'tj', 'tr', 'uk', 'vi', 'zh-CN', 'zh-HK', and 'zh-TW'.
dateFormat String yy-mm-dd (outputs an ISO 8601 standard date) Sets the format to use when outputting the user's chosen date. See the date format section for details.
hint String undefined Displays hint message below the calendar
placeholder String undefined Sets the placeholder for input. Works only if the overrideBrowserDefault is set to true
minDate String undefined Sets the minimum date. Overrides min attrubute from the input field.
maxDate String undefined Sets the maximum date. Overrides max attrubute from the input field.

Using calendar widget alone

There is an option to use the calendar widget without dialog and related input field.

Apart from the options from the listing above you can use any options acceptable by jQueryUI datepicker here.

Exception! The overrideBrowserDefault is not supported here.

Date format

The format can be combinations of the following:

  • d - day of month (no leading zero)
  • dd - day of month (two digit)
  • o - day of the year (no leading zeros)
  • oo - day of the year (three digit)
  • D - day name short
  • DD - day name long
  • m - month of year (no leading zero)
  • mm - month of year (two digit)
  • M - month name short
  • MM - month name long
  • 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
  • anything else - literal text

The default format used by the date picker is yy-mm-dd, which is an ISO 8601 standard format. This will output 2020-01-29.

More date format examples can be found in the jQuery UI documentation .

API reference

Construction

There are two ways to construct a date picker: via the global constructor, or via a jQuery helper. Either approach will return a date picker controller object.

Note: Using the jQuery helper will avoid re-constructing a date picker for the same element multiple times.

Date picker controller methods

Function Arguments Description Example Usage
reconfigure DatePickerOptions object Replaces all configuration options with values. Any unset options will be set to their default values.
destroy —

Removes the date picker or calendar widget from the element, as well as all behaviours and event handlers.

Some notes:

  • In the case of the date picker, the field's type will return to its original value. However, whatever value has been set to by the user will remain.
  • In the case of the calendar widget, all the element's inner HTML will be removed.
  • You can also check for the existence of a destroyPolyfill function. If it is set, calling it will also destroy the date picker widget. This is not recommended, but it is useful when working with previous versions of AUI.