API

Options API Reference

Complete v4.0.0 configuration options reference with grouped structure

Important notice

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

Clock Options

Clock behavior and time configuration options:

Option	Type	Default	Description
`type`	`"12h" \| "24h"`	`"12h"`	Clock format type
`incrementHours`	`number`	`1`	Hour increment step (1, 2, 3, etc.)
`incrementMinutes`	`number`	`1`	Minute increment step (1, 5, 10, 15, etc.)
`autoSwitchToMinutes`	`boolean`	`true`	Auto-switch to minutes after hour selection
`disabledTime`	`DisabledTime`	`undefined`	Disable specific hours, minutes, or intervals
`smoothHourSnap`	`boolean`	`true`	Enable smooth hour dragging with snap animation
`currentTime`	`CurrentTime`	`undefined`	Set current time configuration

UI Options

Visual appearance and display options:

Option	Type	Default	Description
`theme`	`Theme`	`"basic"`	UI theme (basic, dark, m3-green, cyberpunk, blueprint, etc.)
`animation`	`boolean`	`true`	Enable/disable open/close animations
`backdrop`	`boolean`	`true`	Show/hide backdrop overlay
`mobile`	`boolean`	`false`	Force mobile version
`enableSwitchIcon`	`boolean`	`false`	Show desktop/mobile switch icon
`editable`	`boolean`	`false`	Allow manual input editing
`enableScrollbar`	`boolean`	`false`	Keep page scroll when picker is open
`cssClass`	`string`	`undefined`	Additional CSS class for timepicker wrapper
`appendModalSelector`	`string`	`""`	DOM selector to append timepicker (defaults to body)
`iconTemplate`	`string`	`undefined`	Custom HTML template for desktop icon
`iconTemplateMobile`	`string`	`undefined`	Custom HTML template for mobile icon
`inline`	`InlineOptions`	`undefined`	Inline mode configuration
`clearButton`	`boolean`	`false`	Show clear button to reset time selection
`mode`	`"clock" \| "wheel" \| "compact-wheel"`	`"clock"`	Picker mode — analog clock face, scroll-spinner wheels, or headerless wheel

Wheel Options

Wheel / compact-wheel mode configuration via wheel:

Option	Type	Default	Description
`placement`	`"auto" \| "top" \| "bottom"`	`undefined`	Popover placement relative to input in compact-wheel mode
`hideFooter`	`boolean`	`false`	Hide footer (OK/Cancel/Clear buttons) in compact-wheel mode
`commitOnScroll`	`boolean`	`false`	Auto-commit time at end of wheel scrolling without pressing OK
`hideDisabled`	`boolean`	`false`	Completely remove disabled hours/minutes from the wheel list instead of dimming them
`ignoreOutsideClick`	`boolean`	`false`	Prevent the picker from closing when clicking outside its area

Labels Options

Customize all text labels for localization. The accessibility labels (from hourLabel to invalidTimeFormat) are new in v4.4.0:

Option	Type	Default	Description
`am`	`string`	`"AM"`	Custom text for AM label
`pm`	`string`	`"PM"`	Custom text for PM label
`ok`	`string`	`"OK"`	Text for OK button
`cancel`	`string`	`"Cancel"`	Text for cancel button
`time`	`string`	`"Select time"`	Time label for desktop version
`mobileTime`	`string`	`"Enter Time"`	Time label for mobile version
`mobileHour`	`string`	`"Hour"`	Hour label for mobile version
`mobileMinute`	`string`	`"Minute"`	Minute label for mobile version
`clear`	`string`	`"Clear"`	Text for clear button
`hourLabel`	`string`	`"Hour"`	Accessible label for the hour spinbutton
`minuteLabel`	`string`	`"Minute"`	Accessible label for the minute spinbutton
`clockLabel`	`string`	`"Clock"`	Accessible label for the analog clock face group
`periodLabel`	`string`	`"Period"`	Accessible label for the AM/PM period group
`timeLabel`	`string`	`"Time"`	Accessible label for the time wrapper group / tips
`format24Label`	`string`	`"24-hour"`	Accessible label for the 24-hour tips group
`rangeSelectionLabel`	`string`	`"Range selection"`	Accessible label for the range selection tablist
`switchToKeyboardLabel`	`string`	`"Switch to keyboard input"`	Accessible label for the keyboard-input switch icon
`switchToClockLabel`	`string`	`"Switch to clock"`	Accessible label for the clock-view switch icon
`toggleLabel`	`string`	`"Toggle"`	Accessible label for the generic view toggle button
`timezoneSelectorLabel`	`string`	`"Timezone"`	Accessible label for the timezone selector
`announceHour`	`string`	`"Hour"`	Screen-reader announcement prefix for the selected hour
`announceMinute`	`string`	`"Minutes"`	Screen-reader announcement prefix for the selected minutes
`announceAmSelected`	`string`	`"AM selected"`	Screen-reader announcement when AM is selected
`announcePmSelected`	`string`	`"PM selected"`	Screen-reader announcement when PM is selected
`invalidTimeFormat`	`string`	`"Invalid time format"`	Error/announcement text for an invalid time format

Behavior Options

Interaction and accessibility behavior:

Option	Type	Default	Description
`focusInputAfterClose`	`boolean`	`false`	Focus input after closing modal
`focusTrap`	`boolean`	`true`	Trap focus within modal for accessibility
`delayHandler`	`number`	`300`	Debounce delay for buttons (ms)
`id`	`string`	`undefined`	Custom ID for timepicker instance

Callbacks Options

Event handlers and lifecycle callbacks:

Option	Type	Default	Description
`onConfirm`	`(data: ConfirmEventData) => void`	`undefined`	Triggered when user confirms time selection
`onCancel`	`(data: CancelEventData) => void`	`undefined`	Triggered when user cancels
`onOpen`	`(data: OpenEventData) => void`	`undefined`	Triggered when picker opens
`onUpdate`	`(data: UpdateEventData) => void`	`undefined`	Triggered during time changes
`onSelectHour`	`(data: SelectHourEventData) => void`	`undefined`	Triggered when hour is selected
`onSelectMinute`	`(data: SelectMinuteEventData) => void`	`undefined`	Triggered when minute is selected
`onSelectAM`	`(data: SelectAMEventData) => void`	`undefined`	Triggered when AM is selected
`onSelectPM`	`(data: SelectPMEventData) => void`	`undefined`	Triggered when PM is selected
`onError`	`(data: ErrorEventData) => void`	`undefined`	Triggered when validation error occurs
`onTimezoneChange`	`(data: TimezoneChangeEventData) => void`	`undefined`	Triggered when timezone is changed (timezone plugin only)
`onRangeConfirm`	`(data: RangeConfirmEventData) => void`	`undefined`	Triggered when a range is confirmed (range mode only)
`onRangeSwitch`	`(data: RangeSwitchEventData) => void`	`undefined`	Triggered when switching between from/to segments (range mode only)
`onRangeValidation`	`(data: RangeValidationEventData) => void`	`undefined`	Triggered on range validation (range mode only)
`onClear`	`(data: ClearEventData) => void`	`undefined`	Triggered when user clicks the clear button

Timezone Options

Optional timezone selector (requires the timezone plugin) via timezone:

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable timezone selector UI
`default`	`string`	`undefined`	Default timezone ID (e.g. "America/New_York"); browser timezone if not set
`whitelist`	`readonly string[]`	`undefined`	Whitelist of allowed timezone IDs; curated list of common timezones if not set
`label`	`string`	`"Timezone"`	Label for the timezone selector

Range Options

Optional from-to range selection (requires the range plugin) via range:

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable range mode (from-to selection)
`minDuration`	`number`	`undefined`	Minimum duration in minutes
`maxDuration`	`number`	`undefined`	Maximum duration in minutes
`fromLabel`	`string`	`"From"`	Label for the "from" segment
`toLabel`	`string`	`"To"`	Label for the "to" segment

Clear Behavior Options

Control clear button behavior via clearBehavior:

Option	Type	Default	Description
`clearInput`	`boolean`	`true`	Whether clearing also empties the input field value

Available Themes

Choose from 12 built-in themes via ui.theme:

`basic`

Default Material Design theme

`crane`

Google Crane theme with rounded corners

`crane-straight`

Google Crane theme with straight edges

`m3-green`

Material Design 3 (green variant)

`m2`

Material Design 2 classic theme

`dark`

Dark mode theme

`glassmorphic`

Modern glass effect

`pastel`

Soft pastel colors

`ai`

Futuristic AI-inspired theme

`cyberpunk`

Neon cyberpunk aesthetic

`blueprint`

Light precision-instrument look with a cobalt accent (new in v4.4.0)

`blueprint-dark`

Dark sibling of Blueprint on near-black surfaces (new in v4.4.0)

index.tstypescript

1const picker = new TimepickerUI(input, {
2  ui: { theme: 'cyberpunk' }
3});

Inline Mode Configuration

Configure inline mode via ui.inline:

index.tstypescript

1const picker = new TimepickerUI(input, {
2  ui: {
3    inline: {
4      enabled: true,
5      containerId: 'timepicker-container',
6      showButtons: false,  // Hide OK/Cancel buttons
7      autoUpdate: true     // Auto-update input on change
8    }
9  }
10});

Wheel Mode Configuration

Configure wheel/compact-wheel mode via wheel:

index.tstypescript

1const picker = new TimepickerUI(input, {
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  }
8});

Disabled Time Configuration

Disable specific hours, minutes, or intervals via clock.disabledTime:

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    disabledTime: {
4      hours: [1, 3, 5, 8],                    // Disable specific hours
5      minutes: [15, 30, 45],                  // Disable specific minutes
6      interval: '10:00 AM - 12:00 PM',        // Or disable a whole time interval (string or string[])
7    }
8  },
9  wheel: {
10    hideDisabled: true                   // Hide disabled items instead of greying out (wheel modes only)
11  }
12});

Current Time Configuration

Set current time via clock.currentTime:

index.tstypescript

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

Complete v4.0.0 Example

index.tstypescript

1const picker = new TimepickerUI(input, {
2  // Clock options
3  clock: {
4    type: '24h',
5    incrementHours: 1,
6    incrementMinutes: 5,
7    autoSwitchToMinutes: true,
8    disabledTime: {
9      hours: [0, 1, 2, 3],
10      interval: '10:00 - 12:00'
11    },
12    currentTime: {
13      updateInput: true,
14      time: new Date()
15    }
16  },
17  
18  // UI options
19  ui: {
20    theme: 'dark',
21    animation: true,
22    backdrop: true,
23    mobile: false,
24    enableScrollbar: false,
25    enableSwitchIcon: false,
26    editable: false,
27    cssClass: 'custom-picker',
28    appendModalSelector: '#timepicker-container'
29  },
30
31  // Wheel options
32  wheel: {
33    placement: 'bottom',
34    hideFooter: true,
35    commitOnScroll: true,
36    hideDisabled: true,
37    ignoreOutsideClick: false
38  },
39  
40  // Labels options
41  labels: {
42    ok: 'Confirm',
43    cancel: 'Close',
44    time: 'Choose Time',
45    am: 'AM',
46    pm: 'PM',
47    mobileTime: 'Enter Time',
48    mobileHour: 'Hour',
49    mobileMinute: 'Minute'
50  },
51  
52  // Behavior options
53  behavior: {
54    focusTrap: true,
55    focusInputAfterClose: false,
56    delayHandler: 300,
57    id: 'my-timepicker'
58  },
59  
60  // Callbacks options
61  callbacks: {
62    onConfirm: (data) => console.log('Confirmed:', data),
63    onCancel: () => console.log('Cancelled'),
64    onOpen: () => console.log('Opened'),
65    onUpdate: (data) => console.log('Updated:', data),
66    onSelectHour: (data) => console.log('Hour selected:', data.hour),
67    onSelectMinute: (data) => console.log('Minute selected:', data.minutes),
68    onError: (data) => console.error('Error:', data.error)
69  }
70});