A lightweight, customizable javascript timepicker plugin for jQuery inspired by Google Calendar #jQuery-timepicker
Use this plugin to unobtrusively add a timepicker dropdown to your forms. It’s lightweight (2.7kb minified and gzipped) and easy to customize.
Requirements
- jQuery (>= 1.7)
Usage
$('.some-time-inputs').timepicker(options);
options
is an optional javascript object with parameters explained below.
You can also set options as data attributes on the intput elements, like <input type="text" data-time-format="H:i:s" />
. Timepicker still needs to be initialized by calling $('#someElement').timepicker();
.
The defaults for all options are exposed through the $.fn.timepicker.defaults
object. Properties changed in this object (same properties configurable through the constructor) will take effect for every instance created after the change.
Options
- show2400
Show “24:00” as an option when using 24-hour time format.
default: false - appendTo
Override where the dropdown is appended.
Takes either astring
to use as a selector, afunction
that gets passed the clicked input element as argument or a jqueryobject
to use directly.
default: “body” - className
A class name to apply to the HTML element that contains the timepicker dropdown.
default: null - closeOnWindowScroll
Close the timepicker when the window is scrolled. (Replicates<select>
behavior.)
default: false - disableTimeRanges
Disable selection of certain time ranges. Input is an array of time pairs, like `[['3:00am', '4:30am'], ['5:00pm', '8:00pm']]
. The start of the interval will be disabled but the end won’t.default: [] - disableTouchKeyboard
Disable the onscreen keyboard for touch devices.
default: false - durationTime
The time against whichshowDuration
will compute relative times. If this is a function, its result will be used.
default: minTime - forceRoundTime
Force update the time tostep
settings as soon as it loses focus.
default: false - lang
Language constants used in the timepicker. Can override the defaults by passing an object with one or more of the following properties: decimal, mins, hr, hrs.
default:{ am: 'am', pm: 'pm', AM: 'AM', PM: 'PM', decimal: '.', mins: 'mins', hr: 'hr', hrs: 'hrs' }
- maxTime
The time that should appear last in the dropdown list. Can be used to limit the range of time options.
default: 24 hours after minTime - minTime
The time that should appear first in the dropdown list.
default: 12:00am - noneOption
Adds one or more custom options to the top of the dropdown. Can accept several different value types:
Boolean (true
): Adds a “None” option that results in an empty input value
String: Adds an option with a custom label that results in an empty input value
Object: Similar to string, but allows customizing the element’s class name and the resulting input value. Can containlabel
,value
, andclassName
properties.value
must be a string type.
Array: An array of strings or objects to add multiple non-time options
default: false - scrollDefault
If no time value is selected, set the dropdown scroll position to show the time provided, e.g. “09:00”. A time string, Date object, or integer (seconds past midnight) is acceptible, as well as the string'now'
.
default: null - selectOnBlur
Update the input with the currently highlighted time value when the timepicker loses focus.
default: false - show2400
Show “24:00” as an option when using 24-hour time format.
default: false - showDuration
Shows the relative time for each item in the dropdown.minTime
ordurationTime
must be set.
default: false - showOnFocus
Display a timepicker dropdown when the input gains focus.
default: true - step
The amount of time, in minutes, between each item in the dropdown.
default: 30 - timeFormat
How times should be displayed in the list and input element. Uses PHP’s date() formatting syntax. Characters can be escaped with a preceeding double slash (e.g.H\\hi
). Alternatively, you can specify a function instead of a string, to use completely custom time formatting. In this case, the format function receives a Date object and is expected to return a string. default: ‘g:ia’ - typeaheadHighlight
Highlight the nearest corresponding time option as a value is typed into the form input.
default: true - useSelect
Convert the input to an HTML<SELECT>
control. This is ideal for small screen devices, or if you want to prevent the user from entering arbitrary values. This option is not compatible with the following options:appendTo
,closeOnWindowScroll
,disableTouchKeyboard
,forceRoundTime
,scrollDefaultNow
,selectOnBlur
,typeAheadHighlight
.
default: true
Methods
- getSecondsFromMidnight
Get the time as an integer, expressed as seconds from 12am.$('#getTimeExample').timepicker('getSecondsFromMidnight');
- getTime
Get the time using a Javascript Date object, relative to a Date object (default: today).$('#getTimeExample').timepicker('getTime'[, new Date()]);
You can get the time as a string using jQuery’s built-in
val()
function:$('#getTimeExample').val();
- hide
Close the timepicker dropdown.$('#hideExample').timepicker('hide');
- option
Change the settings of an existing timepicker. Callingoption
on a visible timepicker will cause the picker to be hidden.$('#optionExample').timepicker({ 'timeFormat': 'g:ia' }); // initialize the timepicker sometime earlier in your code ... $('#optionExample').timepicker('option', 'minTime', '2:00am'); $('#optionExample').timepicker('option', { 'minTime': '4:00am', 'timeFormat': 'H:i' });
- remove
Unbind an existing timepicker element.$('#removeExample').timepicker('remove');
- setTime
Set the time using a Javascript Date object.$('#setTimeExample').timepicker('setTime', new Date());
- show
Display the timepicker dropdown.$('#showExample').timepicker('show');
Events
- change
The nativeonChange
event will fire any time the input value is updated, whether by selection from the timepicker list or manual entry into the text input. Your code should bind tochange
after initializing timepicker, or use event delegation. - changeTime
Called after a valid time value is entered or selected. SeetimeFormatError
andtimeRangeError
for error events. Fires beforechange
event. - hideTimepicker
Called after the timepicker is closed. - selectTime
Called after a time value is selected from the timepicker list. Fires beforechange
event. - showTimepicker
Called after the timepicker is shown. - timeFormatError
Called if an unparseable time string is manually entered into the timepicker input. Fires beforechange
event. - timeRangeError
Called if a maxTime, minTime, or disableTimeRanges is set and an invalid time is manually entered into the timepicker input. Fires beforechange
event.
Theming
Sample markup with class names:
<input value="5:00pm" class="ui-timepicker-input" type="text">
...
<div class="ui-timepicker-wrapper ui-timepicker-positioned-top optional-custom-classname" tabindex="-1">
<ul class="ui-timepicker-list">
<li>12:00am</li>
<li>12:30am</li>
...
<li>4:30pm</li>
<li class="ui-timepicker-selected">5:00pm</li>
<li class="ui-timepicker-disabled">5:30pm</li>
<li>6:00pm <span class="ui-timepicker-duration">(1 hour)</span></li>
<li>6:30pm</li>
...
<li>11:30pm</li>
</ul>
</div>
The ui-timepicker-positioned-top
class will be applied only when the dropdown is positioned above the input.