Configuration

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

💡

v4.0.0 Breaking Change

Options are now organized into 5 logical groups: clock, ui, labels, behavior, and callbacks. 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	`true`	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

const picker = new TimepickerUI(input, {
  clock: {
    type: '24h',
    incrementHours: 1,
    incrementMinutes: 5,
    autoSwitchToMinutes: false,
    disabledTime: {
      hours: [0, 1, 2, 3],
      interval: ['12:00 PM - 1:00 PM']
    }
  },
  ui: {
    theme: 'dark',
    animation: true,
    backdrop: true,
    mobile: false,
    editable: false,
    enableScrollbar: false,
    enableSwitchIcon: true,
  },
  wheel: {
    placement: 'bottom',
    hideFooter: true,
    commitOnScroll: true
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close',
    time: 'Choose Time'
  },
  behavior: {
    focusTrap: true,
    focusInputAfterClose: false,
    delayHandler: 300
  },
  callbacks: {
    onConfirm: (data) => console.log('Confirmed:', data),
    onCancel: () => console.log('Cancelled'),
    onUpdate: (data) => console.log('Updated:', data)
  }
});

Disabled Time Examples

Disable Specific Hours/Minutes

{
  clock: {
    disabledTime: {
      hours: [1, 3, 5, 23],
      minutes: [15, 30, 45]
    }
  },
  wheel: {
    hideDisabled: true
  }
}

Disable Time Intervals

{
  clock: {
    disabledTime: {
      interval: ['10:00 AM - 2:00 PM', '5:00 PM - 8:00 PM']
    }
  }
}

Inline Mode

{
  ui: {
    inline: {
      enabled: true,
      containerId: 'timepicker-container',
      autoUpdate: true,
      showButtons: false
    }
  }
}

Wheel Mode

{
  ui: { mode: 'wheel' },
  wheel: {
    placement: 'bottom',     // Popover placement (compact-wheel only)
    hideFooter: true,        // Hide OK/Cancel footer
    commitOnScroll: true,    // Commit value on scroll end
    ignoreOutsideClick: true  // Keep open on outside click
  }
}

Current Time

{
  clock: {
    currentTime: {
      updateInput: true,
      locales: 'en-US',
      time: new Date()
    }
  }
}