The Time Picker§

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

$('.timepicker').pickatime()

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,
hiddenPrefix: undefined,
hiddenSuffix: '_submit',

// Editable input
editable: undefined,

// Time intervals
interval: 30,

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

// Root picker container
container: undefined,

// Hidden input container
containerHidden: undefined,

// Close on a user action
closeOnSelect: true,
closeOnClear: true,

// 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',
}

Translations§

The picker can be extended to add support for internationalization. Translations for over 40 languages are available out of the box, which you can include in one of two ways:

// Extend the default picker options for all instances.
$.extend($.fn.pickatime.defaults, {
  clear: 'Effacer'
})

// Or, pass the months and weekdays as an array for each invocation.
$('.timepicker').pickatime({
  clear: 'Effacer'
})

Clear Button§

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

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

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 an optional prefix/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',
  hiddenPrefix: 'prefix__',
  hiddenSuffix: '__suffix'
})

The formatLabel option 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>'
  }
})

Send the hidden value only§

A majority of the time, the value that needs to be sent to the server is just the hidden value – and not the visible one. To make this happen, use the hiddenName option.

This essentially nullifies the hiddenPrefix and hiddenSuffix, strips the name attribute from the source input, and then sets it as the name of the hidden input:

$('.timepicker').pickatime({
  formatSubmit: 'HH:i',
  hiddenName: true
})

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

Editable input§

By default, typing into the input is disabled by giving it a readOnly attribute. Doing so ensures that virtual keyboards don’t pop open on touch devices. It is also a confirmation that values passed to the server will be of a consistent format.

However, this behavior can be changed using the editable option:

$('.timepicker').pickatime({
  editable: true
})

Using HTML5 attributes§

Because each input is readOnly by default, HTML5 attributes, such as required and pattern, do not get enforced.

To enable default browser behavior on these attributes, set the editable property to true.

Intervals§

Choose the minutes interval between each time in the list:

$('.timepicker').pickatime({
  interval: 150
})

Time Limits§

Set the minimum and maximum selectable times on the picker.

Using JavaScript dates§

$('.datepicker').pickadate({
  min: new Date(2015,3,20,7),
  max: new Date(2015,7,14,18,30)
})

Using arrays formatted as [HOUR,MINUTE]§

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

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
})

Disable Times§

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

Using JavaScript dates§

$('.timepicker').pickatime({
  disable: [
    new Date(2016,3,20,4,30),
    new Date(2016,3,20,9)
  ]
})

Using arrays formatted as [HOUR,MINUTE]§

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

Using integers as hours (0 to 23)§

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

Using objects as a range of times§

$('.timepicker').pickatime({
  disable: [
    { from: [2,0], to: [5,30] }
  ]
})

The values for from & to can be:

• A JavaScript Date object,
• An array formatted as [HOUR,MINUTE],
• And true to set it as “now”.

The values can also be integers representing time intervals relative to the other:

• to can only be positive:

  { from: [3,0], to: 10 }

• from can only be negative:

  { from: -10, to: true }

Disabling all with a set of exceptions§

Enable only 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]
  ]
})

Disabling ranges with exceptions§

Enable times that fall within a range of disabled times by adding the inverted parameter to the item within the collection:

$('.timepicker').pickatime({
  disable: [
    1,
    [1, 30, 'inverted'],
    { from: [4, 30], to: [10, 30] },
    [6, 30, 'inverted'],
    { from: [8, 0], to: [9, 0], inverted: true }
  ]
})

container§

By default, the picker’s root element is inserted right after the input element. Specify where to insert the root element by passing any valid CSS selector or jQuery object to this option:

$('.timepicker').pickatime({
  container: '#root-picker-outlet'
})

container for the hidden input§

By default, the picker’s hidden input is inserted right after the main input element. Specify where to insert the hidden element by passing any valid CSS selector to this option:

$('.datepicker').pickadate({
  containerHidden: '#hidden-input-outlet'
})

Close on a user action §

When a time is selected or the “clear” button is pressed, the picker closes. To change this behavior, use the following options:

$('.timepicker').pickatime({
  closeOnSelect: false,
  closeOnClear: false
})

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(context) {
    console.log('Just set stuff:', context)
  }
})

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

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

To learn more on how to use the picker object, read the API documentation.