Time Picker

Add timepicker to a text input. AutoInit() starts every .timepicker except those marked no-autoinit.

The clock is inline, not a modal. It is appended to the input’s parent and stays visible. There is no openByDefault flag.

<div class="field">
  <input type="text" class="time-picker" id="lunchtime">
  <label for="lunchtime">Lunchtime</label>
</div>

Wrap the input in its own .field (or another small parent). The clock is appended inside that parent.

Click a hour on the dial, then a minute. With the default autoSubmit: true, finishing the minute writes the input (HH:MM AM or HH:MM PM). You can also type in the digital hour and minute fields.

Initialization

The IIFE bundle exposes Expressive.Timepicker. Call init yourself when you need options other than the defaults, or let Expressive.AutoInit() start every .timepicker. Unlike Datepicker, the default options already show the clock.

document.addEventListener('DOMContentLoaded', function() {
  const elems = document.querySelectorAll('.timepicker');
  const instances = Expressive.Timepicker.init(elems, {
    // specify options here
  });
});

Per-instance options can also be passed through AutoInit:

Expressive.AutoInit(document.body, {
  Timepicker: { twelveHour: false }
});

Display

The clock is a .timepicker-container in the page. There is no overlay and no autoClose option.

container renders the clock into a specific element instead of the input’s parent. Pass a selector or a DOM node.

Docked popover

displayPlugin: 'docked' wraps the clock in a .display-docked popover that appears when the input is clicked or confirmed with Enter, and hides when you click outside.

Expressive.Timepicker.init(elem, {
  displayPlugin: 'docked'
});

The popover is positioned in document coordinates and then appended to the input’s parent. A position: relative parent — including .field — shifts that position, so the clock will not sit next to the field. Prefer a static wrapper if you use docked, or keep the clock inline.

Optional displayPluginOptions: margin (default 5), transition (10), duration (250), and align ('left').

Options

Name	Type	Default	Description
duration	Number	350	Transition between the hours and minutes views, in milliseconds.
container	Element or String	null	Element or selector to render the clock into. When omitted, it is appended to the input’s parent.
showClearBtn	Boolean	false	Show a Clear button in the footer.
autoSubmit	Boolean	true	If true, choosing a minute writes the input. If false, Ok and Cancel buttons are added.
defaultTime	String	'now'	Initial time. 'now' or a 'HH:MM' string (optionally with AM/PM).
fromNow	Number	0	Millisecond offset added to 'now'.
i18n	Object	See below	Labels for Cancel, Clear, and Ok.
twelveHour	Boolean	true	If true, use a 12-hour clock with AM/PM. If false, use 24-hour hours on two rings.
vibrate	Boolean	true	Vibrate the device when the clock hand changes value.
onSelect	Function	null	Called when a time is chosen on the dial. Receives (hour, minute).
onInputInteraction	Function	null	Called when the input is clicked or confirmed with Enter.
onDone	Function	null	Called when the Ok button is used. Only created when autoSubmit is false.
onCancel	Function	null	Called when the Cancel button is used. Only created when autoSubmit is false.
displayPlugin	String	null	Set to 'docked' for a click-to-open popover.
displayPluginOptions	Object	null	Options for the docked plugin: margin, transition, duration, align.

Internationalization

Pass a partial i18n object. Missing keys keep the English defaults.

Key	Default
cancel	'Cancel'
clear	'Clear'
done	'Ok'

12-hour and 24-hour

twelveHour defaults to true. The intro clock above is 12-hour with AM/PM. Set twelveHour: false for a 24-hour dial: hours 1–12 on the inner ring, 13–00 on the outer ring. The written value is then HH:MM with no meridian.

Expressive.Timepicker.init(document.getElementById('timepicker-24'), {
  twelveHour: false
});

Methods

All methods are called on the plugin instance. You can get the instance like this:

const instance = Expressive.Timepicker.getInstance(elem);

.showView();

Show the hours or minutes face.

String: 'hours' or 'minutes'.

instance.showView('hours');

.done();

Write the current hours and minutes to the input. Pass a truthy argument to clear the input instead.

instance.done();
instance.done(true);

.clear();

Clear the input. Same as done(true).

instance.clear();

.destroy();

Destroy the plugin instance, remove the clock, and tear down its event handlers.

instance.destroy();

Properties

Name	Type	Description
el	Element	The input the plugin was initialized with.
options	Object	The options the instance was initialized with.
time	String	The last value written by done(), without the AM/PM suffix.
hours	Number	The hour currently shown on the clock.
minutes	Number	The minute currently shown on the clock.
amOrPm	String	'AM' or 'PM' when twelveHour is true.
currentView	String	'hours' or 'minutes'.