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.

Demo code
Result
AخA
 
<input class="aui-date-picker" id="demo-range-1" type="date" max="2012-01-25" min="2011-12-25" />
 
const demo1 = document.getElementById('demo-range-1');
const controller = new AJS.DatePicker(demo1, {'overrideBrowserDefault': true});

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

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.

Demo code
Result
<>
March 2025
SuMoTuWeThFrSa
      1
2345678
9101112131415
16171819202122
23242526272829
3031     
This will be a hint message below the calendar.
 
<div id="demo-calendar-container"></div>
 
const demo2 = document.getElementById('demo-calendar-container');
const controller = new AJS.CalendarWidget(demo2, {
    max: '2012-01-25',
    min: '2011-12-25',
    hint: 'This will be a hint message below the calendar.'
});

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.

Demo code
 
// "el" should be a non-null HTMLElement
const el = document.querySelector('.my-field');
// "options" are listed further up this page
const options = { ... };
​x
 
let controller;
// attach a date picker to an HTML input field via global
controller = new AJS.DatePicker(el, options);
​
// attach a date picker to an HTML input field via jQuery helper
controller = AJS.$(el).datePicker(options);
​
// render a calendar widget in to el via global
controller = new AJS.CalendarWidget(el, options);
​
// render a calendar widget in to el via jQuery helper
controller = AJS.$(el).calendarWidget(options);

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.
 
controller.reconfigure({ firstDay: 5 });
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.
 
controller.destroy();