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

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

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: CallbackData) => void`	`undefined`	Triggered when user confirms time selection
`onCancel`	`(data: CallbackData) => void`	`undefined`	Triggered when user cancels
`onOpen`	`() => void`	`undefined`	Triggered when picker opens
`onUpdate`	`(data: CallbackData) => void`	`undefined`	Triggered during time changes
`onSelectHour`	`(data: CallbackData) => void`	`undefined`	Triggered when hour is selected
`onSelectMinute`	`(data: CallbackData) => void`	`undefined`	Triggered when minute is selected
`onSelectAM`	`() => void`	`undefined`	Triggered when AM is selected
`onSelectPM`	`() => void`	`undefined`	Triggered when PM is selected
`onError`	`(data: CallbackData) => void`	`undefined`	Triggered when validation error occurs
`onClear`	`(data: ClearEventData) => void`	`undefined`	Triggered when user clicks the clear button

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 10 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

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

Inline Mode Configuration

Configure inline mode via ui.inline:

const picker = new TimepickerUI(input, {
  ui: {
    inline: {
      enabled: true,
      containerId: 'timepicker-container',
      showButtons: false,  // Hide OK/Cancel buttons
      autoUpdate: true     // Auto-update input on change
    }
  }
});

Wheel Mode Configuration

Configure wheel/compact-wheel mode via wheel:

const picker = new TimepickerUI(input, {
  ui: { mode: 'wheel' },
  wheel: {
    placement: 'bottom',     // Popover placement (compact-wheel only)
    hideFooter: true,        // Hide OK/Cancel footer
    commitOnScroll: true     // Commit value on scroll end
  }
});

Disabled Time Configuration

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

const picker = new TimepickerUI(input, {
  clock: {
    disabledTime: {
      hours: [1, 3, 5, 8],              // Disable specific hours
      minutes: [15, 30, 45],            // Disable specific minutes
      interval: 15,                     // Or use interval shorthand (15, 30, etc.)
    }
  },
  wheel: {
    hideDisabled: true                   // Hide disabled items instead of greying out (wheel modes only)
  }
});

Current Time Configuration

Set current time via clock.currentTime:

const picker = new TimepickerUI(input, {
  clock: {
    currentTime: {
      updateInput: true,
      locales: 'en-US',
      time: new Date()
    }
  }
});

Complete v4.0.0 Example

const picker = new TimepickerUI(input, {
  // Clock options
  clock: {
    type: '24h',
    incrementHours: 1,
    incrementMinutes: 5,
    autoSwitchToMinutes: true,
    disabledTime: {
      hours: [0, 1, 2, 3],
      interval: 15
    },
    currentTime: {
      updateInput: true,
      time: new Date()
    }
  },
  
  // UI options
  ui: {
    theme: 'dark',
    animation: true,
    backdrop: true,
    mobile: false,
    enableScrollbar: false,
    enableSwitchIcon: false,
    editable: false,
    cssClass: 'custom-picker',
    appendModalSelector: '#timepicker-container'
  },

  // Wheel options
  wheel: {
    placement: 'bottom',
    hideFooter: true,
    commitOnScroll: true,
    hideDisabled: true,
    ignoreOutsideClick: false
  },
  
  // Labels options
  labels: {
    ok: 'Confirm',
    cancel: 'Close',
    time: 'Choose Time',
    am: 'AM',
    pm: 'PM',
    mobileTime: 'Enter Time',
    mobileHour: 'Hour',
    mobileMinute: 'Minute'
  },
  
  // Behavior options
  behavior: {
    focusTrap: true,
    focusInputAfterClose: false,
    delayHandler: 300,
    id: 'my-timepicker'
  },
  
  // Callbacks options
  callbacks: {
    onConfirm: (data) => console.log('Confirmed:', data),
    onCancel: () => console.log('Cancelled'),
    onOpen: () => console.log('Opened'),
    onUpdate: (data) => console.log('Updated:', data),
    onSelectHour: (data) => console.log('Hour selected:', data.hour),
    onSelectMinute: (data) => console.log('Minute selected:', data.minutes),
    onError: (data) => console.error('Error:', data.error)
  }
});