Guide

Configuration

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

v4.0.0 Breaking Change

Options are now organized into 9 logical groups: clock, ui, labels, behavior, callbacks, timezone, range, wheel, and clearBehavior. See migration guide in the changelog.

Clock Options

Configure clock behavior, format, and time restrictions:

Property	Type	Default	Description
`type`	12h \| 24h	`12h`	Clock format
`incrementHours`	number	`1`	Hour increment step
`incrementMinutes`	number	`1`	Minute increment step
`autoSwitchToMinutes`	boolean	`true`	Auto-switch after hour
`disabledTime`	object	`undefined`	Disable specific times
`smoothHourSnap`	boolean	`true`	Smooth hour dragging with snap
`currentTime`	boolean \| object	`undefined`	Set current time

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
`mobile`	boolean	`false`	Force mobile mode
`ui.enableSwitchIcon`	boolean	`false`	Show mode switch icon
`editable`	boolean	`false`	Allow manual input
`enableScrollbar`	boolean	`false`	Keep scrollable
`cssClass`	string	`undefined`	Custom CSS class
`appendModalSelector`	string	`""`	Custom container
`iconTemplate`	string	`SVG`	Desktop icon
`iconTemplateMobile`	string	`SVG`	Mobile icon
`inline`	object	`undefined`	Inline mode config
`clearButton`	boolean	`false`	Show clear button
`mode`	clock \| wheel \| compact-wheel	`clock`	Picker mode

Wheel Options

Wheel / compact-wheel mode configuration:

Property	Type	Default	Description
`placement`	auto \| top \| bottom	`undefined`	Popover placement (compact-wheel only)
`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 all text labels and button texts:

Property	Type	Default	Description
`am`	string	`AM`	AM label
`pm`	string	`PM`	PM label
`ok`	string	`OK`	OK button
`cancel`	string	`Cancel`	Cancel button
`time`	string	`Select time`	Desktop label
`mobileTime`	string	`Enter Time`	Mobile label
`mobileHour`	string	`Hour`	Mobile hour
`mobileMinute`	string	`Minute`	Mobile minute
`clear`	string	`Clear`	Clear button text

Behavior Options

Control focus, delays, and instance behavior:

Property	Type	Default	Description
`focusInputAfterClose`	boolean	`false`	Focus input on close
`focusTrap`	boolean	`true`	Trap focus in modal
`delayHandler`	number	`300`	Click delay (ms)
`id`	string	`auto`	Custom instance ID

Clear Behavior Options

Control clear button behavior:

Property	Type	Default	Description
`clearInput`	boolean	`true`	Whether clearing also empties the input

Callbacks Options

Event handlers for user interactions:

Property	Type	Default	Description
`onConfirm`	function	`undefined`	Time confirmed
`onCancel`	function	`undefined`	Cancelled
`onOpen`	function	`undefined`	Picker opened
`onUpdate`	function	`undefined`	Time updated
`onSelectHour`	function	`undefined`	Hour selected
`onSelectMinute`	function	`undefined`	Minute selected
`onSelectAM`	function	`undefined`	AM selected
`onSelectPM`	function	`undefined`	PM selected
`onError`	function	`undefined`	Error occurred
`onClear`	function	`undefined`	Time cleared

Complete Example

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    type: '24h',
4    incrementHours: 1,
5    incrementMinutes: 5,
6    autoSwitchToMinutes: false,
7    disabledTime: {
8      hours: [0, 1, 2, 3],
9      interval: ['12:00 PM - 1:00 PM']
10    }
11  },
12  ui: {
13    theme: 'dark',
14    animation: true,
15    backdrop: true,
16    mobile: false,
17    editable: false,
18    enableScrollbar: false,
19    enableSwitchIcon: true,
20  },
21  wheel: {
22    placement: 'bottom',
23    hideFooter: true,
24    commitOnScroll: true
25  },
26  labels: {
27    ok: 'Confirm',
28    cancel: 'Close',
29    time: 'Choose Time'
30  },
31  behavior: {
32    focusTrap: true,
33    focusInputAfterClose: false,
34    delayHandler: 300
35  },
36  callbacks: {
37    onConfirm: (data) => console.log('Confirmed:', data),
38    onCancel: () => console.log('Cancelled'),
39    onUpdate: (data) => console.log('Updated:', data)
40  }
41});

Disabled Time Examples

Disable Specific Hours/Minutes

index.tstypescript

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 Time Intervals

index.tstypescript

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

Inline Mode

index.tstypescript

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

Wheel Mode

index.tstypescript

1{
2  ui: { mode: 'wheel' },
3  wheel: {
4    placement: 'bottom',     // Popover placement (compact-wheel only)
5    hideFooter: true,        // Hide OK/Cancel footer
6    commitOnScroll: true,    // Commit value on scroll end
7    ignoreOutsideClick: true  // Keep open on outside click
8  }
9}

Current Time

index.tstypescript

1{
2  clock: {
3    currentTime: {
4      updateInput: true,
5      locales: 'en-US',
6      time: new Date()
7    }
8  }
9}