Datepicker Widget version added: 1.0
Description: Select a date from a popup or inline calendar
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 date ranges and add in buttons and other navigation options easily.
By default, the datepicker calendar 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
While the datepicker is open, the following key 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. Open the datepicker if 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 the next week.
- ENTER: Select the focused date.
- CTRL+END: Close the datepicker and erase the date.
- ESCAPE: Close the datepicker without selection.
Utility functions
$.datepicker.setDefaults( settings )
Change the default settings for all date pickers.
Use the option()
method to change settings for individual instances.
Set all date pickers to open on focus or a click on an icon.
1
2
3
4
5
6
|
|
Set all date pickers to have French text.
1
|
|
$.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 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
There are also a number of predefined standard date formats available from $.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".
1
|
|
Display the date in expanded French format. Produces "Samedi, Juillet 14, 2007".
1
2
3
4
5
6
|
|
$.datepicker.parseDate( format, value, settings )
Extract a date from a string value with a specified 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 year (no leading zeros)
- oo - day of 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
A number of exceptions may be thrown:
- 'Invalid arguments' if either format or value is null
- 'Missing number at position nn' if format indicated a numeric value that is not then found
- 'Unknown name at position nn' if format indicated day or month name that is not then found
- 'Unexpected literal at position nn' if format indicated a literal value that is not then found
- 'Invalid date' if the date is invalid, such as '31/02/2007'
Extract a date in ISO format.
1
|
|
Extract a date in expanded French format.
1
2
3
4
5
6
7
|
|
$.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 a 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 of first week of the current year, and that 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.
Find the week of the year for a date.
1
|
|
$.datepicker.noWeekends
Set as beforeShowDay function to prevent selection of weekends.
We can provide the noWeekends()
function into the beforeShowDay
option which will calculate all the weekdays and provide an array of true
/false
values indicating whether a date is selectable.
Set the DatePicker so no weekend is selectable
1
2
3
|
|
Localization
Datepicker provides support for localizing its content to cater for different languages and date formats. Each localization is contained within its own file with the language code appended to the name, e.g., jquery.ui.datepicker-fr.js
for French. The desired localization file should be included after the main datepicker code. Each localization file adds its settings to the set of available localizations and automatically applies them as defaults for all instances.
The $.datepicker.regional
attribute holds an array of localizations, indexed by language code, with ""
referring to the default (English). Each entry is an object with the following attributes: closeText
, prevText
, nextText
, currentText
, monthNames
, monthNamesShort
, dayNames
, dayNamesShort
, dayNamesMin
, weekHeader
, dateFormat
, firstDay
, isRTL
, showMonthAfterYear
, and yearSuffix
.
You can restore the default localizations with:
$.datepicker.setDefaults( $.datepicker.regional[ "" ] );
And can then override an individual datepicker for a specific locale:
$( selector ).datepicker( $.datepicker.regional[ "fr" ] );
Dependencies
- UI Core
- Effects Core (optional; for use with the
showAnim
option)
Additional Notes:
- This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.
- This widget manipulates its element's value programmatically, therefore a native change may not be fired when the element's value changes.
Options
altFieldType: Selector or jQuery or Element
""
altFormat
option to change the format of the date within this field. Leave as blank for no alternate field.Initialize the datepicker with the altField option specified:
1
|
|
Get or set the altField option, after initialization:
1
2
3
4
5
|
|
altFormatType: String
""
dateFormat
to be used for the altField
option. This allows one date format to be shown to the user for selection purposes, while a different format is actually sent behind the scenes. For a full list of the possible formats see the [[UI/Datepicker/formatDate|formatDate]] functionInitialize the datepicker with the altFormat option specified:
1
|
|
Get or set the altFormat option, after initialization:
1
2
3
4
5
|
|
appendTextType: String
""
Initialize the datepicker with the appendText option specified:
1
|
|
Get or set the appendText option, after initialization:
1
2
3
4
5
|
|
autoSizeType: Boolean
false
true
to automatically resize the input field to accommodate dates in the current dateFormat
.Initialize the datepicker with the autoSize option specified:
1
|
|
Get or set the autoSize option, after initialization:
1
2
3
4
5
|
|
beforeShowType: Function( Element input, Object inst )
null
beforeShowDayType: Function( Date date )
null
[0]
equal to true
/false
indicating whether or not this date is selectable, [1]
equal to a CSS class name or ""
for the default presentation, and [2]
an optional popup tooltip for this date. It is called for each day in the datepicker before it is displayed.calculateWeekType: Function()
jQuery.datepicker.iso8601Week
Initialize the datepicker with the calculateWeek option specified:
1
|
|
Get or set the calculateWeek option, after initialization:
1
2
3
4
5
|
|
changeMonthType: Boolean
false
Initialize the datepicker with the changeMonth option specified:
1
|
|
Get or set the changeMonth option, after initialization:
1
2
3
4
5
|
|
changeYearType: Boolean
false
yearRange
option to control which years are made available for selection.Initialize the datepicker with the changeYear option specified:
1
|
|
Get or set the changeYear option, after initialization:
1
2
3
4
5
|
|
closeTextType: String
"Done"
showButtonPanel
option to display this button.Initialize the datepicker with the closeText option specified:
1
|
|
Get or set the closeText option, after initialization:
1
2
3
4
5
|
|
constrainInputType: Boolean
true
true
, entry in the input field is constrained to those characters allowed by the current dateFormat
option.Initialize the datepicker with the constrainInput option specified:
1
|
|
Get or set the constrainInput option, after initialization:
1
2
3
4
5
|
|
currentTextType: String
"Today"
showButtonPanel
option to display this button.Initialize the datepicker with the currentText option specified:
1
|
|
Get or set the currentText option, after initialization:
1
2
3
4
5
|
|
dateFormatType: String
"mm/dd/yy"
[[UI/Datepicker/formatDate|formatDate]]
function.Initialize the datepicker with the dateFormat option specified:
1
|
|
Get or set the dateFormat option, after initialization:
1
2
3
4
5
|
|
dayNamesType: Array
[ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ]
dateFormat
option.Initialize the datepicker with the dayNames option specified:
1
|
|
Get or set the dayNames option, after initialization:
1
2
3
4
5
|
|
dayNamesMinType: Array
[ "Su", "Mo", "Tu", "We", "Th", "Fr", "Sa" ]
Initialize the datepicker with the dayNamesMin option specified:
1
|
|
Get or set the dayNamesMin option, after initialization:
1
2
3
4
5
|
|
dayNamesShortType: Array
[ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
dateFormat
option.Initialize the datepicker with the dayNamesShort option specified:
1
|
|
Get or set the dayNamesShort option, after initialization:
1
2
3
4
5
|
|
defaultDateType: Date or Number or String
null
[[UI/Datepicker#option-dateFormat|dateFormat]]
, or a number of days from today (e.g. +7) or a string of values and periods ('y' for years, 'm' for months, 'w' for weeks, 'd' for days, e.g. '+1m +7d'), or null for today.- Date: A date object containing the default date.
- Number: A number of days from today. For example
2
represents two days from today and-1
represents yesterday. - String: A string in the format defined by the
dateFormat
option, or a relative date. Relative dates must contain value and period pairs; valid periods are"y"
for years,"m"
for months,"w"
for weeks, and"d"
for days. For example,"+1m +7d"
represents one month and seven days from today.
Initialize the datepicker with the defaultDate option specified:
1 |
|
Get or set the defaultDate option, after initialization:
1 2 3 4 5 |
|
durationType: or String
"normal"
Initialize the datepicker with the duration option specified:
1
|
|
Get or set the duration option, after initialization:
1
2
3
4
5
|
|
firstDayType: Integer
0
0
, Monday is 1
, etc.Initialize the datepicker with the firstDay option specified:
1
|
|
Get or set the firstDay option, after initialization:
1
2
3
4
5
|
|
gotoCurrentType: Boolean
false
true
, the current day link moves to the currently selected date instead of today.Initialize the datepicker with the gotoCurrent option specified:
1
|
|
Get or set the gotoCurrent option, after initialization:
1
2
3
4
5
|
|
hideIfNoPrevNextType: Boolean
false
minDate
and maxDate
options). You can hide them altogether by setting this attribute to true
.Initialize the datepicker with the hideIfNoPrevNext option specified:
1
|
|
Get or set the hideIfNoPrevNext option, after initialization:
1
2
3
4
5
|
|
isRTLType: Boolean
false
Initialize the datepicker with the isRTL option specified:
1
|
|
Get or set the isRTL option, after initialization:
1
2
3
4
5
|
|
maxDateType: Date or Number or String
null
null
, there is no maximum.- Date: A date object containing the maximum date.
- Number: A number of days from today. For example
2
represents two days from today and-1
represents yesterday. - String: A string in the format defined by the
dateFormat
option, or a relative date. Relative dates must contain value and period pairs; valid periods are"y"
for years,"m"
for months,"w"
for weeks, and"d"
for days. For example,"+1m +7d"
represents one month and seven days from today.
Initialize the datepicker with the maxDate option specified:
1 |
|
Get or set the maxDate option, after initialization:
1 2 3 4 5 |
|
minDateType: Date or Number or String
null
null
, there is no minimum.- Date: A date object containing the minimum date.
- Number: A number of days from today. For example
2
represents two days from today and-1
represents yesterday. - String: A string in the format defined by the
dateFormat
option, or a relative date. Relative dates must contain value and period pairs; valid periods are"y"
for years,"m"
for months,"w"
for weeks, and"d"
for days. For example,"+1m +7d"
represents one month and seven days from today.
Initialize the datepicker with the minDate option specified:
1 |
|
Get or set the minDate option, after initialization:
1 2 3 4 5 |
|
monthNamesType: Array
[ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ]
dateFormat
option.Initialize the datepicker with the monthNames option specified:
1
|
|
Get or set the monthNames option, after initialization:
1
2
3
4
5
|
|
monthNamesShortType: Array
[ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ]
dateFormat
option.Initialize the datepicker with the monthNamesShort option specified:
1
|
|
Get or set the monthNamesShort option, after initialization:
1
2
3
4
5
|
|
nextTextType: String
"Next"
Initialize the datepicker with the nextText option specified:
1
|
|
Get or set the nextText option, after initialization:
1
2
3
4
5
|
|
numberOfMonthsType: Number or Array
1
- Number: The number of months to display in a single row.
- Array: An array defining the number of rows and columns to display.
Initialize the datepicker with the numberOfMonths option specified:
1 |
|
Get or set the numberOfMonths option, after initialization:
1 2 3 4 5 |
|
onChangeMonthYearType: Function( Integer year, Integer month, Object inst )
null
this
refers to the associated input field.onCloseType: Function( String dateText, Object inst )
null
""
if none) and the datepicker instance as parameters. this
refers to the associated input field.onSelectType: Function( String dateText, Object inst )
null
this
refers to the associated input field.prevTextType: String
"Prev"
Initialize the datepicker with the prevText option specified:
1
|
|
Get or set the prevText option, after initialization:
1
2
3
4
5
|
|
selectOtherMonthsType: Boolean
false
showOtherMonths
option is set to true
.Initialize the datepicker with the selectOtherMonths option specified:
1
|
|
Get or set the selectOtherMonths option, after initialization:
1
2
3
4
5
|
|
shortYearCutoffType: Number or String
"+10"
[[UI/Datepicker#option-dateFormat|dateFormat]]
'y'). Any dates entered with a year value less than or equal to the cutoff year are considered to be in the current century, while those greater than it are deemed to be in the previous century.- Number: A value between
0
and99
indicating the cutoff year. - String: A relative number of years from the current year, e.g.,
"+3"
or"-5"
.
Initialize the datepicker with the shortYearCutoff option specified:
1 |
|
Get or set the shortYearCutoff option, after initialization:
1 2 3 4 5 |
|
showAnimType: String
"show"
"show"
(the default), "slideDown"
, "fadeIn"
, any of the jQuery UI effects. Set to an empty string to disable animation.Initialize the datepicker with the showAnim option specified:
1
|
|
Get or set the showAnim option, after initialization:
1
2
3
4
5
|
|
showButtonPanelType: Boolean
false
Initialize the datepicker with the showButtonPanel option specified:
1
|
|
Get or set the showButtonPanel option, after initialization:
1
2
3
4
5
|
|
showCurrentAtPosType: Number
0
numberOfMonths
option, the showCurrentAtPos
option defines which position to display the current month in.Initialize the datepicker with the showCurrentAtPos option specified:
1
|
|
Get or set the showCurrentAtPos option, after initialization:
1
2
3
4
5
|
|
showMonthAfterYearType: Boolean
false
Initialize the datepicker with the showMonthAfterYear option specified:
1
|
|
Get or set the showMonthAfterYear option, after initialization:
1
2
3
4
5
|
|
showOnType: String
"focus"
"focus"
), when a button is clicked ("button"
), or when either event occurs ("both"
).Initialize the datepicker with the showOn option specified:
1
|
|
Get or set the showOn option, after initialization:
1
2
3
4
5
|
|
showOptionsType: Object
{}
showAnim
option, you can provide additional settings for that animation via this option.Initialize the datepicker with the showOptions option specified:
1
|
|
Get or set the showOptions option, after initialization:
1
2
3
4
5
|
|
showOtherMonthsType: Boolean
false
selectOtherMonths
option.Initialize the datepicker with the showOtherMonths option specified:
1
|
|
Get or set the showOtherMonths option, after initialization:
1
2
3
4
5
|
|
showWeekType: Boolean
false
true
, a column is added to show the week of the year. The calculateWeek
option determines how the week of the year is calculated. You may also want to change the firstDay
option.Initialize the datepicker with the showWeek option specified:
1
|
|
Get or set the showWeek option, after initialization:
1
2
3
4
5
|
|
stepMonthsType: Number
1
Initialize the datepicker with the stepMonths option specified:
1
|
|
Get or set the stepMonths option, after initialization:
1
2
3
4
5
|
|
weekHeaderType: String
"Wk"
showWeek
option to display this column.Initialize the datepicker with the weekHeader option specified:
1
|
|
Get or set the weekHeader option, after initialization:
1
2
3
4
5
|
|
yearRangeType: String
"c-10:c+10"
"-nn:+nn"
), relative to the currently selected year ("c-nn:c+nn"
), absolute ("nnnn:nnnn"
), or combinations of these formats ("nnnn:-nn"
). Note that this option only affects what appears in the drop-down, to restrict which dates may be selected use the minDate
and/or maxDate
options.Initialize the datepicker with the yearRange option specified:
1
|
|
Get or set the yearRange option, after initialization:
1
2
3
4
5
|
|
yearSuffixType: String
""
Initialize the datepicker with the yearSuffix option specified:
1
|
|
Get or set the yearSuffix option, after initialization:
1
2
3
4
5
|
|
Methods
destroy()
-
This method does not accept any arguments.
Invoke the destroy method:
1
|
|
dialog( date [, onSelect ] [, settings ] [, pos ] )
-
dateThe initial date.
-
onSelectType: Function()A callback function when a date is selected. The function receives the date text and date picker instance as parameters.
-
settingsType: OptionsThe new settings for the date picker.
-
posType: Number[2] or MouseEventThe position of the top/left of the dialog as
[x, y]
or aMouseEvent
that contains the coordinates. If not specified the dialog is centered on the screen.
Invoke the dialog method:
1
|
|
getDate()Returns: Date
null
if no date has been selected.-
This method does not accept any arguments.
Invoke the getDate method:
1
|
|
hide()
-
This method does not accept any arguments.
Invoke the hide method:
1
|
|
isDisabled()Returns: Boolean
-
This method does not accept any arguments.
Invoke the isDisabled method:
1
|
|
option( optionName )Returns: Object
optionName
.-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
|
option()Returns: PlainObject
-
This method does not accept any arguments.
Invoke the method:
1
|
|
option( optionName, value )
optionName
.-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
|
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
|
refresh()
-
This method does not accept any arguments.
Invoke the refresh method:
1
|
|
setDate( date )
Date
object or a string in the current date format (e.g., "01/26/2009"
), a number of days from today (e.g., +7
) or a string of values and periods ("y"
for years, "m"
for months, "w"
for weeks, "d"
for days, e.g., "+1m +7d"
), or null
to clear the selected date.-
dateThe new date.
Invoke the setDate method:
1
|
|
show()
-
This method does not accept any arguments.
Invoke the show method:
1
|
|
widget()Returns: jQuery
jQuery
object containing the datepicker.-
This method does not accept any arguments.
Invoke the widget method:
1
|
|
Example:
A simple jQuery UI Datepicker.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
|