qcTimepicker

Simple jQuery dropdown timepicker. Small, accessible, and highly customizable.

Demo

Documentation

Installation

Bower (recommended)

bower install qcTimepicker

Manually

Download the files in the dist/ directory.

Usage

Load the plugin by including the script on the page:

<script src='path/to/qcTimepicker.min.js' charset='utf-8'></script>

Initialization

Initialize the plugin by calling the .qcTimepicker() function on a jQuery object:

$('.timepickers').qcTimepicker();

Please note that only input elements will be initialized.

It is strongly recommended that the input elements have the type time, although all inputs that match the selector will be initialized.

Labels that are associated with the affected input element will be mapped to the newly created dropdown element.

Options

Options can be set during the initialization process by passing in an object as a parameter:

$('.timepickers').qcTimepicker({
    step: 900
});

classes

Type: string or Array

Default: '' (empty string)

If specified, the class(es) will be applied to the each of the dropdowns created by qcTimepicker.

format

Type: string

Default: 'H:mm'

The format of the time as displayed in the dropdown. ICU symbols are used for the format. Supported symbols include: a, h, hh, H, HH, k, kk, K, KK, m, mm, s, ss, A

To insert a literal symbol into the output string, escape the character with a backslash. Currently, output strings cannot contain backslashes.

minTime

Type: string or Date

Default: '00:00:00' (midnight)

The minimum time (lower-bound of range) in the dropdown. The value must be specified as a string in 24-hour format or as a Date object. If a string is given, less-significant units may be omitted if they are zero. Hours are required.

Examples:

• '11' => '11:00:00'
• '11:00' => '11:00:00'
• '11:30' => '11:30:00'

Leading zeros may be omitted:

• '11:3' => '11:03:00'

Awkward times will be converted if possible:

• '11:90:87' => '12:31:27'
• '28:30:00' => '04:30:00'

Ignored if a min attribute is specified on the element of initialization.

If the min attribute in the HTML is used, the value MUST be specified in the official format: HH:mm:ss (Hours and minutes separated by colons, optionally followed by a colon and number of seconds. Leading zeros are required on all parts.)

maxTime

Type: string or Date

Default: '23:59:59'

The maximum time (upper-bound of range) in the dropdown. See minTime for format.

Ignored if a max attribute is specified on the element of initialization.

If the max attribute in the HTML is used, the value MUST be specified in the official format: HH:mm:ss (Hours and minutes separated by colons, optionally followed by a colon and number of seconds. Leading zeros are required on all parts.)

step

Type: number

Default: 1800 (30 minutes)

The intervals of time displayed in the dropdown. The value represents the number of seconds between each interval.

Ignored if a step attribute is specified on the element of initialization.

placeholder

Type: string

Default: The text of an input element's placeholder attribute, if not present, a hyphen will be displayed.

The text to display in the placeholder option. This is the first option containing an empty value.

Ignored if a data-placeholder attribute or placeholder attribute is specified on the element of initialization.

Methods

Toggle visibility

The visibility of the dropdown can be toggled by calling qcTimepicker with the parameters 'show' and 'hide', respectively.

$('input').qcTimepicker('show');
$('input').qcTimepicker('hide');

Destroy

To uninstantiate qcTimepicker and restore the original input, call qcTimepicker with the 'destroy' parameter:

$('input').qcTimepicker('destroy');

Step (increment and decrement)

To programatically increment or decrement the value in accordance with the step, call qcTimepicker with the stepUp or stepDown parameters, respectively.

This behaviour is consistent with the methods stepUp and stepDown on the HTMLInputElement interface.

<input value='08:00:00'>

$('input').qcTimepicker({
    step: '02:00:00'
});

$('input').qcTimepicker('stepUp');
$('input').val() // returns 10:00:00

$('input').qcTimepicker('stepDown');
// Time is now back to 8:00
$('input').val() // returns 08:00:00

Numeric and date values

qcTimepicker supports retrieving the time value as a number or a JavaScript Date object. In the case of a number, the value returned is in milliseconds.

This behaviour is consistent with the properties valueAsNumber and valueAsDate on the HTMLInputElement interface.

<input value='08:00:00'>

$('input').qcTimepicker();

// As a number
var foo = $('input').qcTimepicker('valueAsNumber');
console.log(foo); // outputs 28800000

// As a Date
var bar = $('input').qcTimepicker('valueAsDate');

// The string output above differs based on your computer's current time zone
console.log(bar); // outputs Thu Jan 01 1970 03:00:00 GMT-0500 (Eastern Standard Time)

// Call getTime() or valueOf() for a primitive value
console.log(bar.getTime()); // outputs 28800000