The Time Picker§

The basic setup requires targetting an `input` element and invoking the picker:

$('.timepicker').pickatime()

{%= timeDemoField({ klass: 'js__timepicker' }) %}

Options§

With the basic invocation above, these are the default settings:

// Translations and clear button
clear: 'Clear',

// Formats
format: 'h:i A',
formatLabel: undefined,
formatSubmit: undefined,
hiddenSuffix: '_submit',

// Time intervals
interval: 30,

// Time limits
min: undefined,
max: undefined,

// Disable times
disable: undefined,

// Events
onStart: undefined,
onRender: undefined,
onOpen: undefined,
onClose: undefined,
onSet: undefined,
onStop: undefined,

// Classes
klass: {

    // The element states
    input: 'picker__input',
    active: 'picker__input--active',

    // The root picker and states *
    picker: 'picker picker--time',
    opened: 'picker--opened',
    focused: 'picker--focused',

    // The picker holder
    holder: 'picker__holder',

    // The picker frame, wrapper, and box
    frame: 'picker__frame',
    wrap: 'picker__wrap',
    box: 'picker__box',

    // List of times
    list: 'picker__list',
    listItem: 'picker__list-item',

    // Time states
    disabled: 'picker__list-item--disabled',
    selected: 'picker__list-item--selected',
    highlighted: 'picker__list-item--highlighted',
    viewset: 'picker__list-item--viewset',
    now: 'picker__list-item--now',

    // Clear button
    buttonClear: 'picker__button--clear',
}

* It is important to not add any stylings to the picker’s root element. Instead, target the .picker__holder element (or any other within) based on the state of the root element.

Translations§

Coming soon...

Clear Button§

Change the text or hide the button completely by passing a false-y value:

$('.timepicker').pickatime({
    clear: ''
})

{%= timeDemoField({ id: 'time_demo__buttons' }) %}

Formats§

Display a human-friendly label and input format and use an alternate one to submit.

This is done by creating a new hidden input element with the same name attribute as the original and a suffix:

$('.timepicker').pickatime({
    // Escape any “rule” characters with an exclamation mark (!).
    format: 'T!ime selected: h:i a',
    formatLabel: '<b>h</b>:i <!i>a</!i>',
    formatSubmit: 'HH:i',
    hiddenSuffix: '--submit'
})

{%= timeDemoField({ id: 'time_demo__formats--a' }).replace( 'type=text', 'name=time_demo__formats type=text' ) %}

formatLabel is unique. It can contain HTML and it can also be a function if you want to create the label during run-time:

$('.timepicker').pickatime({
    formatLabel: function(time) {
        var hours = ( time.pick - this.get('now').pick ) / 60,
            label = hours < 0 ? ' !hours to now' : hours > 0 ? ' !hours from now' : 'now'
        return 'h:i a <sm!all>' + ( hours ? Math.abs(hours) : '' ) + label + '</sm!all>'
    }
})

{%= timeDemoField({ id: 'time_demo__formats--b' }).replace( 'type=text', 'name=time_demo__formats type=text' ) %}

Formatting Rules§

The following rules can be used to format any time:

Rule	Description	Result
`h`	Hour in 12-hour format	1 – 12
`hh`	Hour in 12-hour format with a leading zero	01 – 12
`H`	Hour in 24-hour format	0 – 23
`HH`	Hour in 24-hour format with a leading zero	00 – 23
`i`	Minutes	00 – 59
`a`	Day time period	a.m. / p.m.
`A`	Day time period in uppercase	AM / PM

Intervals§

Choose the minutes interval between each time in the list:

$('.datepicker').pickadate({
    interval: 150
})

{%= dateDemoField({ id: 'time_demo__interval' }) %}

Time Limits§

Set the minimum and maximum selectable times on the picker.

1) Using arrays formatted as [HOUR,MINUTE]:

$('.timepicker').pickatime({
    min: [7,30],
    max: [14,0]
})

{%= timeDemoField({ id: 'time_demo__limits--a' }) %}

2) As times relative to now using integers or a boolean:

$('.timepicker').pickatime({
    // An integer (positive/negative) sets it as intervals relative from now.
    min: -5,
    // `true` sets it to now. `false` removes any limits.
    max: true
})

{%= timeDemoField({ id: 'time_demo__limits--b' }) %}

Disable Times§

Disable a specific or arbitrary set of times selectable on the picker.

1) Using arrays formatted as [HOUR,MINUTE]:

$('.timepicker').pickatime({
    disable: [
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--a' }) %}

2) Using integers representing hours (from 0 to 23):

$('.timepicker').pickatime({
    disable: [
        3, 5, 7
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--b' }) %}

3) Disabling all except a specific or arbitrary set of times by setting true as the first item in the collection:

$('.timepicker').pickatime({
    disable: [
        true,
        3, 5, 7,
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--c' }) %}

events§

Fire off events as the user interacts with the picker:

$('.timepicker').pickatime({
    onStart: function() {
        console.log('Hello there :)')
    },
    onRender: function() {
        console.log('Whoa.. rendered anew')
    },
    onOpen: function() {
        console.log('Opened up')
    },
    onClose: function() {
        console.log('Closed now')
    },
    onStop: function() {
        console.log('See ya.')
    },
    onSet: function(event) {
        console.log('Just set stuff:', event)
    }
})

{%= timeDemoField({ id: 'time_demo__events' }).replace( 'Try me', 'Open your console and try me' ) %}

Within scope of all six of these events, this refers to the picker.

The onSet event is the only callback that is passed an event argument that provides a bit of context as to which properties are being “set”.