Configuration

Complete configuration guide for v4.0.0 (grouped options structure)

Examples: With Backdrop Current Time Editable Input Increment Steps

v4.0.0 Breaking Change

Options are now organized into groups: clock, ui, labels, behavior, callbacks, timezone, range and wheel. See the migration guide. This page uses the option names from 4.5.0. The older names still work until 5.0 and are listed in Renamed in 4.5.0.

Clock Options

#

Configure clock behavior, format, and time restrictions:

Property	Type	Default	Description
`type`	12h \| 24h \| auto	`12h`	Clock format. auto picks 12h or 24h from the browser locale
`incrementHours`	number	`1`	Hour step on the clock, the wheel and the arrow keys (1, 2, 3, 4 or 6)
`incrementMinutes`	number	`1`	Minute increment step
`autoSwitchToMinutes`	boolean	`true`	Auto-switch after hour
`showSeconds`	boolean	`false`	Show seconds (values become HH:MM:SS)
`incrementSeconds`	1 \| 5 \| 10 \| 15 \| 20 \| 30	`1`	Seconds increment step
`autoSwitchToSeconds`	boolean	`true`	Auto-switch after minute (with showSeconds)
`disabledTime`	object	`undefined`	Disable hours, minutes, seconds or time ranges
`discreteHourJump`	boolean	`false`	Move the hour hand from hour to hour while dragging instead of following the pointer
`defaultTime`	'now' \| object	`undefined`	Time shown while the input is empty. 'now' also writes the current time to the input

UI Options

#

Customize appearance, theme, and display modes:

Property	Type	Default	Description
`theme`	string	`basic`	Theme name
`animation`	boolean	`true`	Enable animations
`backdrop`	boolean	`true`	Show backdrop
`initialView`	clock \| keyboard	`clock`	View shown when the picker opens
`viewSwitch`	boolean	`false`	Show the clock / keyboard view switch
`editable`	boolean	`false`	Allow manual input
`allowPageScroll`	boolean	`false`	Let the page scroll while open. When false, the page is locked and --tp-scrollbar-gap on <html> holds the removed scrollbar width
`cssClass`	string	`undefined`	Custom CSS class
`appendTo`	string \| HTMLElement	`""`	Element or selector the modal is appended to (body when empty)
`keyboardIcon`	string	`""`	Keyboard switch icon as raw HTML (built-in icon when empty). Trusted markup only
`clockIcon`	string	`""`	Clock switch icon as raw HTML (built-in icon when empty). Trusted markup only
`inline`	object	`undefined`	Inline mode config
`clearButton`	boolean \| { clearInput }	`false`	Show clear button. { clearInput: false } keeps the input value on Clear
`mode`	clock \| wheel \| compact-wheel	`clock`	Picker mode

keyboardIcon and clockIcon are inserted as raw HTML, so pass only trusted markup. Every other label and text option is escaped.

Scroll lock and fixed headers

With allowPageScroll: false (the default), the page cannot scroll while the picker is open as a modal. Inline pickers and the compact-wheel popover do not lock it. The lock is set on <html>, and also on <body> when the body is the element that scrolls. If a scrollbar disappears, the picker adds its width as right padding, so the page content does not move.

That padding does not reach position: fixed elements. While the page is locked, <html> has --tp-scrollbar-gap set to the width of the removed scrollbar (0px when there was none). Use it to keep a fixed header from jumping:

index.css

1.site-header {
2  padding-right: var(--tp-scrollbar-gap, 0px);
3}

The variable is removed when the last open picker closes.

Wheel Options

#

Wheel / compact-wheel mode configuration:

Property	Type	Default	Description
`placement`	auto \| top \| bottom	`undefined`	Compact-wheel popover placement. When unset, compact-wheel opens as a modal. auto: below if there is room, otherwise above. top / bottom: that side while it has room for at least three wheel rows, otherwise the other side
`hideFooter`	boolean	`false`	Hide footer in compact-wheel mode
`commitOnScroll`	boolean	`false`	Auto-commit time at scroll end
`hideDisabled`	boolean	`false`	Remove disabled values from wheel list
`ignoreOutsideClick`	boolean	`false`	Keep picker open on outside click

Labels Options

#

Customize the main text labels and button texts. The full list, including the accessibility labels, is on the Options page:

Property	Type	Default	Description
`am`	string	`AM`	AM label
`pm`	string	`PM`	PM label
`ok`	string	`OK`	OK button
`cancel`	string	`Cancel`	Cancel button
`clockTitle`	string	`Select time`	Heading of the clock face view
`keyboardTitle`	string	`Enter Time`	Heading of the keyboard view
`hour`	string	`Hour`	Hour field caption, accessible name and announcement
`minute`	string	`Minute`	Minute field caption, accessible name and announcement
`second`	string	`Second`	Second field caption, accessible name and announcement (with showSeconds)
`clear`	string	`Clear`	Clear button text

Behavior Options

#

Control focus, delays, and instance behavior:

Property	Type	Default	Description
`returnFocus`	boolean	`false`	Return focus to the input when the picker closes. true is recommended, and 5.0 makes it the default
`focusTrap`	boolean	`true`	Trap focus in modal
`delayHandler`	number	`0`	Extra delay (ms) before the picker starts to close
`id`	string	`undefined`	Custom instance ID for TimepickerUI.getById()

Callbacks Options

#

Event handlers for user interactions. Plugin and wheel callbacks are listed on the Events page:

Property	Type	Default	Description
`onConfirm`	function	`undefined`	Time confirmed
`onCancel`	function	`undefined`	Cancelled
`onOpen`	function	`undefined`	Picker opened
`onShow`	function	`undefined`	User asked to open the picker
`onUpdate`	function	`undefined`	Time updated
`onSelectHour`	function	`undefined`	Hour selected
`onSelectMinute`	function	`undefined`	Minute selected
`onSelectSecond`	function	`undefined`	Second selected (with showSeconds)
`onSelectPeriod`	function	`undefined`	AM or PM selected, with { type }
`onSwitchFace`	function	`undefined`	Clock face switched between hours, minutes and seconds
`onSwitchView`	function	`undefined`	View switched (with viewSwitch)
`onError`	function	`undefined`	Error occurred
`onClear`	function	`undefined`	Time cleared

Complete Example

#

index.ts

1const picker = new TimepickerUI(input, {
2  clock: {
3    type: '24h',
4    incrementHours: 1,
5    incrementMinutes: 5,
6    autoSwitchToMinutes: false,
7    showSeconds: true,
8    incrementSeconds: 5,
9    disabledTime: {
10      ranges: ['00:00 - 03:59', '12:00 - 13:00']
11    }
12  },
13  ui: {
14    theme: 'dark',
15    animation: true,
16    backdrop: true,
17    initialView: 'clock',
18    editable: false,
19    allowPageScroll: false,
20    viewSwitch: true,
21    clearButton: { clearInput: false }
22  },
23  wheel: {                   // used by the wheel modes only
24    hideFooter: true,
25    commitOnScroll: true
26  },
27  labels: {
28    ok: 'Confirm',
29    cancel: 'Close',
30    clockTitle: 'Choose Time'
31  },
32  behavior: {
33    focusTrap: true,
34    returnFocus: true,
35    delayHandler: 0
36  },
37  callbacks: {
38    onConfirm: (data) => console.log('Confirmed:', data),
39    onCancel: () => console.log('Cancelled'),
40    onUpdate: (data) => console.log('Updated:', data)
41  }
42});

Disabled Time Examples

#

Disable Specific Hours/Minutes

index.ts

1{
2  clock: {
3    disabledTime: {
4      hours: [1, 3, 5, 23],
5      minutes: [15, 30, 45]
6    }
7  },
8  wheel: {
9    hideDisabled: true
10  }
11}

Disable Seconds

index.ts

1{
2  clock: {
3    showSeconds: true,
4    disabledTime: {
5      seconds: [55, 56, 57, 58, 59]
6    }
7  }
8}

Disable Time Ranges

When ranges is set, the hours, minutes and seconds lists are ignored. Edges can carry seconds. See Seconds.

index.ts

1{
2  clock: {
3    disabledTime: {
4      ranges: ['10:00 AM - 2:00 PM', '5:00 PM - 8:00 PM']
5    }
6  }
7}

Inline Mode

#

index.ts

1{
2  ui: {
3    inline: {
4      enabled: true,
5      container: '#timepicker-container',
6      autoUpdate: true,
7      showButtons: false
8    }
9  }
10}

Wheel Mode

#

index.ts

1import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
2import { WheelPlugin } from 'timepicker-ui/plugins/wheel';
3
4PluginRegistry.register(WheelPlugin);
5
6const picker = new TimepickerUI(input, {
7  ui: { mode: 'compact-wheel' },
8  wheel: {
9    placement: 'bottom',      // Popover below the input; unset = modal
10    hideFooter: true,         // No OK/Cancel/Clear footer (compact-wheel only)
11    commitOnScroll: true,     // Commit value on scroll end
12    ignoreOutsideClick: true  // Keep open on outside click
13  }
14});
15picker.create();

Default Time

#

'now' shows the current time and writes it to the input. The object form with updateInput: false only shows the time in the picker.

index.ts

1{
2  clock: {
3    defaultTime: 'now'
4  }
5}
6
7{
8  clock: {
9    defaultTime: { time: new Date(2026, 0, 1, 9, 30), updateInput: false }
10  }
11}