Methods

create()

Initialize the timepicker. Must be called before using other methods. If clock.disabledTime is invalid, create() reports it through the error event and the picker does not open.

1const picker = new TimepickerUI(input);
2picker.create();

open(callback?)

Open the timepicker programmatically. It emits open, not show.

1picker.open();
2
3picker.open(() => {
4  console.log('Picker opened');
5});

close(update?, callback?)

Close the timepicker. close(true) commits the current selection like clicking OK: the input is updated and confirm is emitted. Nothing is committed while OK is disabled. With true, the callback runs once the picker has closed. Without it, the selection is discarded and the callback runs at once.

1picker.close();
2
3picker.close(true, () => {
4  console.log('Value committed and picker closed');
5});

getValue()

Get the current time. seconds is present only with clock.showSeconds, and time then includes it. degreesHours and degreesMinutes are deprecated and will be removed in 5.0. Use hour and minutes instead.

1const value = picker.getValue();
2
3// 12h
4{
5  hour: '10',
6  minutes: '30',
7  type: 'AM',
8  time: '10:30 AM',
9  degreesHours: 300,     // deprecated
10  degreesMinutes: 180    // deprecated
11}
12
13// 12h with clock.showSeconds
14{
15  hour: '10',
16  minutes: '30',
17  seconds: '15',
18  type: 'AM',
19  time: '10:30:15 AM',
20  degreesHours: 300,     // deprecated
21  degreesMinutes: 180    // deprecated
22}

setValue(time, updateInput?)

Set the time programmatically. Use HH:MM for 24h and H:MM AM or H:MM PM for 12h. With clock.showSeconds, HH:MM:SS and H:MM:SS AM/PM work too, and a value without seconds means :00. Without it, seconds in the string are dropped. A time in the other clock format is converted, so '2:30 PM' sets 14:30 in a 24h picker. A string that is not a time, such as '25:00' or 'abc', leaves the value as it was and emits error (callbacks.onError). In range mode (RangePlugin and range.enabled) it sets the end being edited, see getActivePart(), and with updateInput writes 'from - to' to the input.

1// clock: { type: '12h' }
2picker.setValue('10:30 AM');
3picker.setValue('14:30');        // converted, the input shows 02:30 PM
4
5// clock: { type: '24h' }, input text left unchanged
6picker.setValue('15:45', false);
7
8// clock: { type: '24h', showSeconds: true }
9picker.setValue('14:30:15');
10
11// clock: { type: '12h', showSeconds: true }
12picker.setValue('2:30:15 PM');

setOptions(options)

Change options at runtime. Groups you leave out keep their values. An open picker is re-rendered with the new options, and a selection that was not confirmed yet is reset to the input value. With a range, the active end (From or To) and the times already set are kept, and keeping To emits range:switch. The view (clock or keyboard) is kept too, unless the call changes ui.initialView: then an open picker switches to the new initial view and emits switch:view once, after the new view is shown. A closed picker emits nothing and opens in the new view. With a range, a time typed into the active end is committed first and emits range:change. When clock.type or clock.showSeconds changes, a valid time in the input, including a range (from - to), is rewritten in the new format without an update or confirm event. An empty or invalid input is left as it is. Options that fail validation are reported through the error event and callbacks.onError, and the old options stay. New in 4.5.0.

1picker.setOptions({
2  ui: {
3    theme: 'dark'
4  },
5  clock: {
6    type: '24h'
7  }
8});

update({ options, create? }, callback?)

Deprecated and removed in 5.0. Use setOptions(options). It applies options the same way. create: true calls create() afterwards, and the callback runs only when the options were valid.

1// Deprecated
2picker.update({ options: { ui: { theme: 'dark' } } });
3
4// Use instead
5picker.setOptions({ ui: { theme: 'dark' } });

setRange({ from?, to? }, updateInput?)

Set one or both ends of the range. Each time uses the setValue() format. An end you leave out keeps its value, and null or '' clears it. With range.linked (the default), clearing From while To is active switches back to From. updateInput defaults to true and writes 'from - to' to the input, with --:-- for an empty end, or nothing when both ends are empty. It works while the picker is open or closed and emits range:validation, but not range:change. When the end shown on the clock does not change, the dial and the typed fields are left alone. range:switch for the before-From limit fires only when From actually changed. On an open picker in wheel or compact-wheel mode the wheel moves to the active end quietly, without update or select:* events. In clock mode it still emits select:hour and update. Needs RangePlugin and range.enabled: without them it emits error and does nothing. A time that is not valid, or an object with neither end, emits error and leaves the range as it was.

1picker.setRange({ from: '09:00', to: '17:00' });
2
3picker.setRange({ from: '9:00 AM', to: '5:00 PM' }, false);
4
5picker.setRange({ from: '09:00' });
6picker.setRange({ to: null });

getRange()

Read both ends of the range. Returns { from, to }, where each end is { hour, minutes, seconds?, type? } or null until it is complete. A time typed in a field counts as soon as it is applied on blur or Enter, or when you switch ends, so getRange() then returns it. Returns null, and emits error, without RangePlugin or range.enabled.

1const range = picker.getRange();
2
3// { from: { hour: '09', minutes: '00' }, to: { hour: '17', minutes: '00' } }

setActivePart('from' | 'to')

Switch the clock or the wheel to one end of the range without moving focus. On an open picker, a time typed into the current end is committed first, and that emits range:change when the value of that end changes. Then it updates the tabs and emits range:switch. Returns true when the active end changed or was already that end. With the default range.linked, 'to' is refused until From is complete and the method returns false. In wheel and compact-wheel mode the wheel shows the end quietly, without update or select:* events. In clock mode it still emits select:hour and update. While the picker is closed, setActivePart('to') emits nothing, and the next open emits range:switch. When the end shown does not change, the dial stays as it is.

1picker.open();
2
3const switched = picker.setActivePart('to');

getActivePart()

Read the range end being edited. Returns 'from' or 'to'. Returns null after destroy(), and also without RangePlugin or range.enabled, where it emits error like getRange().

1if (picker.getActivePart() === 'from') {
2  picker.setActivePart('to');
3}

setRangeCaptions({ from?, to? })

Show a second line under a range tab label, for example the date of that end. The text is plain text, not HTML, and becomes part of the tab's accessible name. A tab you leave out keeps its caption, and null or '' removes it. Works open or closed, survives setOptions() and Clear, and emits no event. Needs RangePlugin and range.enabled, otherwise it emits error.

1picker.setRangeCaptions({ from: 'Wed Oct 21', to: 'Thu Oct 22' });
2
3picker.setRangeCaptions({ to: null });

clear()

Clear the picker like the Clear button: empties the input (unless ui.clearButton is { clearInput: false }), returns the clock or wheel to its neutral time and empties both range ends. It works open or closed, and without ui.clearButton. It emits clear and update like the button, makes no screen reader announcement and never moves focus. It does not emit range:change.

picker.clear();

setView(view) / getView()

Show the clock face or the keyboard view, for example from your own switch button. Open: switches at once and emits switch:view. Closed: the next open starts in that view, and later opens start in ui.initialView again. Focus does not move, unless it was on the part that gets hidden: then it moves to the active time field. setView() returns true when that view is shown or will be at the next open. It returns false, without an error, in wheel and compact-wheel modes and after destroy(), and returns false and emits error for a value other than 'clock' or 'keyboard'. getView() returns the view shown now, or the view the next open starts in, and null in wheel modes or after destroy().

1picker.setView('keyboard');
2
3const view = picker.getView();

refreshDisabledTime()

Apply clock.disabledTime and clock.isTimeDisabled again without a re-render. It clears the cached isTimeDisabled results and updates the disabled marks on the clock or wheel and the OK button. It does not write to the input. Safe to call while the picker is closed.

1let lunchBreak = false;
2
3const picker = new TimepickerUI(input, {
4  clock: {
5    type: '24h',
6    isTimeDisabled: ({ hour }) => lunchBreak && hour === 12
7  }
8});
9picker.create();
10
11lunchBreak = true;
12picker.refreshDisabledTime();

on(event, handler) / once(event, handler)

Subscribe to an event. Both return a function that removes the handler, and calling it more than once does nothing. With once(), the function removes the handler before it runs. The event name is typed as TimepickerEventName, so the handler gets the payload type of that event. See Events for off().

1const unsubscribe = picker.on('confirm', (data) => {
2  console.log(data.hour, data.minutes);
3});
4
5unsubscribe();

destroy(options?)

Destroy the picker instance and clean up.

1picker.destroy();
2
3picker.destroy({
4  keepInputValue: true,
5  callback: () => console.log('Destroyed')
6});

getElement()

Get the root wrapper element.

const wrapper = picker.getElement();

1import { parseTime } from 'timepicker-ui';
2
3parseTime('2:30 PM', { clockType: '24h' });
4// { hour: '14', minutes: '30' }
5
6parseTime('abc');
7// null

1import { formatTime } from 'timepicker-ui';
2
3formatTime({ hour: '2', minutes: '30', type: 'PM' });
4// '02:30 PM'

1import { createDisabledTimeCheck } from 'timepicker-ui';
2
3const isDisabled = createDisabledTimeCheck({
4  type: '24h',
5  disabledTime: { ranges: ['12:00 - 13:00'] }
6});
7
8isDisabled('12:30');                               // true
9isDisabled({ hour: 9, minutes: 0, seconds: 0 });   // false

1const picker = new TimepickerUI(input, {
2  behavior: { id: 'my-picker' }
3});
4picker.create();
5
6const instance = TimepickerUI.getById('my-picker');

1const allPickers = TimepickerUI.getAllInstances();
2console.log(allPickers.length);

TimepickerUI.destroyAll();

1if (TimepickerUI.isAvailable('#timepicker')) {
2  console.log('Element exists in DOM');
3}