The datepicker() control provides the user with the ability to choose a date from a highly customizable calender. Datepicker also offers many methods that allow you to programmatically manipulate it.
Initialize the datepicker() via JavaScript (accepting default options):
Initialize the datepicker() via JavaScript specifying your own options:
$().ready() executes that have data-initialize="datepicker" on them will be initialized immediatelydata-initialize="datepicker" after $.ready() executes will initialize when a mousedown event occurs on them.The datepicker() markup is complex and specific. On initialization, the datepicker() plugin searches inside of the specified element for the components used to build the control. For your convenience, we have written the required markup for you. Writing custom datepicker() markup is not recommended; if you choose to do so, understanding the datepicker.js code will be necessary.
If initializing through JavaScript, datepicker() allows you to specify options.
| Name | type | default | description |
|---|---|---|---|
| allowPastDates | boolean | false | Dictates whether past dates can be input or selected by the user. |
| date | Date object, string, or falsy value ('', null, or false) | new Date() | Specifies the date that is set upon initialization. If using a string, the format must be a valid date string as supported by the browser or by moment.js if available. Falsy values will result in no date being set upon initialization. |
| formatDate | function or null | null | Function that is called for formatting a valid date object. Should only be overriden if the datepicker's default formatDate method is not sufficient for your needs. The formatDate function takes a date object as an argument, and should return a string. |
| momentConfig | object | { culture: 'en', format: 'L' } |
Settings used to configure moment.js, if available. Both culture and format
attributes must be present for moment features to be utilized. The culture attribute is a string
representing the desired datepicker() language. The format attribute is a string representing the
desired date format that appears in the input upon date selection. Consult the moment.js
docs for more information on supported cultures and formats. |
| parseDate | function or null | null | Function that is called for parsing date strings input by the user. Should only be overriden if the
datepicker's default parseDate method is not sufficient for your needs. The parseDate function takes a
date object, string, or falsy value as an argument, and should return either a valid date object representing
the successfully parsed value or invalid date object (new Date(NaN)) |
| restricted | array | [] | Specifies dates that are restricted from user input and selection. Uses an array of objects to provide
the ranges. Each of the object must have the following format: { from: '03/31/2015', to: '03/31/2016' }, but multiple ranges are supported. The from attribute represents the start date of the restricted range, and the to attribute represents the end date of the range, inclusively. Both attributes can be set to either a valid date
string or a date object. -Infinity and Infinity are valid delimiters. View this gist to see how to set the datepicker to only allow dates from the past 365 days. |
| sameYearOnly | boolean | false | Prevents the user from selecting dates outside the current year if true. |
| twoDigitYearProtection | boolean | true | Attempts to accommodate for people entering two digit years. Only works if moment is being used to parse date. Otherwise browser parsing is used (which is inconsistent) |
MomentJS parsing is the same format for the API as the output within the input element. Datepicker's default MomentJS locale is regionalistic (American). If you are using MomentJS (and it is recommended that you do), option strings such as those within restricted date ranges expect the format that you provide within momentConfig. Locales and formats are available in the MomentJS documentation. The default locale configuration is momentConfig: { culture: 'en', format: 'L' }
Therefore if you do not specify your own locale and format, restricted will be expecting an array of objects of the'MM/DD/YYYY' format--that is the 'L' MomentJS format. An example of this would be restricted: [{ from: '08/10/2014', to: '08/15/2014' }]
datepicker() to date provided. Date provided must be a valid Date object or date string.
{% highlight js %}$('#myDatepicker').datepicker('setDate', new Date());{% endhighlight %}
datepicker() is currently using. Only available using moment.js with langsdatepicker() uses. Only available using moment.js with langs
{% highlight js %}$('#myDatepicker').datepicker('setCulture', 'fr');{% endhighlight %}
datepicker() is currently using. Only available using moment.js with langsdatepicker() uses. Only available using moment.js with langs
{% highlight js %}$('#myDatepicker').datepicker('setFormat', 'L');{% endhighlight %}
| Event Type | Description |
|---|---|
| changed.fu.datepicker | This event is fired when the date value has been changed by the user inputing text into the input box. Choosing the date by clicking in the datepicker will not fire this event. Arguments include event, date where date is a JavaScript Date object. |
| dateClicked.fu.datepicker | This event is fired when a day has been selected on the calendar. Arguments include event, date where date is a JavaScript Date object. |
| inputParsingFailed.fu.datepicker | This event is fired when an invalid date is parsed on blur of the datepicker. Arguments include event, date where date is a JavaScript Date object. |
| inputRestrictedDate.fu.datepicker | This event is fired when an restricted date is parsed on blur of the datepicker. Arguments include event, date where date is a JavaScript Date object. |
All datepicker() events are fired on the .datepicker classed element.
To listen for changes on the Date() object, you will need to combine two listeners (as shown below). The reason for this is to keep double events firing when a date is clicked (previously when a date was clicked dateClicked and changed would both fire, which was confusing to many people.
To listen for all changes to the datepicker's input value, including setting the date to invalid values, you will need to combine two listeners:
Choose a date from a calendar dropdown, with input parsing and formatting. Works with moment.js for extended functionality.
To support various date formats around the world, datepicker() has an optional dependency on moment.js. Download moment.js (with locales).