Timepicker-UI
Latest Release

What's New

Stay up to date with the latest features and improvements

💡

Version 4.2.0 Released!

March 18, 2026 - Wheel mode, compact-wheel, clear button, landscape fixes, and more

What's new:

  • Wheel mode - Scroll-spinner interface replacing the analog clock face. Enable via ui.mode: 'wheel'
  • Compact-wheel mode - Headerless wheel picker without the hour/minute inputs header. Enable via ui.mode: 'compact-wheel'
  • Popover placement - Use wheel.placement to open compact-wheel as a popover anchored to the input ('auto', 'top', 'bottom')
  • Hide disabled options - Set wheel.hideDisabled: true to completely remove disabled values instead of dimming them
  • Auto-commit on scroll - Set wheel.commitOnScroll: true to auto-confirm time at scroll end without pressing OK
  • Clear button - Reset time selection with a dedicated button, enabled by default via ui.clearButton
  • clearBehavior options - Control whether clearing empties the input value with clearBehavior.clearInput
  • onClear callback & event - New callback and EventEmitter event with previousValue payload
  • New exported types - ClearEventData, ClearBehaviorOptions, WheelScrollStartEventData, WheelScrollEndEventData
  • Persist on outside click - Set wheel.ignoreOutsideClick: true to keep the picker open when clicking outside its area (wheel and compact-wheel modes)
  • Race condition fix - Rapidly clicking the input before the modal fully opened no longer causes the picker to get stuck invisible in the DOM or permanently blocks the input
  • Range landscape fix - From/To tabs now properly positioned in landscape orientation
  • Timezone landscape fix - Timezone picker layout corrected in landscape orientation with CSS Grid
  • AM/PM border theming - Landscape border color now uses theme variable instead of hardcoded black
View full changelog
💡

Version 4.1.0

January 31, 2026 - New features and UX improvements

What's new:

  • Range Plugin - New! Select time ranges with start/end pickers, duration calculation, and validation
  • Timezone Plugin - New! Timezone selector with searchable dropdown and UTC offset display
  • Plugin architecture - Tree-shakeable plugins for smaller core bundle size
  • Smooth hour snapping - Fluid hour dragging with animation (new default)
View full changelog

What's New in v4.0.0

Version 4.0.0 brought major improvements in architecture, TypeScript support, and developer experience.

Grouped Options Architecture

Options are now organized into logical groups for better clarity and maintainability.

Old API (v3.x)

const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'dark',
  mobile: true,
  animation: true,
  incrementMinutes: 5,
  okLabel: 'Confirm',
  cancelLabel: 'Close'
});

New API (v4.0.0)

const picker = new TimepickerUI(input, {
  clock: {
    type: '12h',
    incrementMinutes: 5
  },
  ui: {
    theme: 'dark',
    mobile: true,
    animation: true
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close'
  }
});

Five Main Groups

  • clock: Time format, increments, disabled times, auto-switch behavior
  • ui: Theme, animations, mobile mode, backdrop, icons
  • labels: All text labels (OK, Cancel, AM/PM, etc.)
  • behavior: Focus trap, delays, input focus after close
  • callbacks: All event handlers in one place

Enhanced TypeScript Support

Complete type safety with strict interfaces and better IntelliSense.

  • Fully typed options with detailed documentation
  • Typed event payloads for all callbacks
  • Better autocomplete in modern IDEs
  • Strict mode compatible (no any, no unknown)

New Features

Keyboard Navigation

Use Arrow Up/Down keys to increment/decrement hour and minute values with live clockface updates.

  • • Works in both 12h and 24h modes
  • • Proper wrap-around (59→00, 12→01)
  • • Smooth clock hand animations

Improved Accessibility

Dynamic tabindex management ensures hidden elements are not focusable.

Glassmorphic Theme

New theme with backdrop-filter blur effect for modern glass UI.

Architecture Improvements

  • Composition over Inheritance: No class hierarchies, only explicit composition
  • Manager Pattern: Independent, testable managers for each concern
  • SSR Safety: Full compatibility with Next.js, Nuxt, Remix, and other SSR frameworks
  • Pure State Container: Centralized state with no side effects
  • Event-Driven: Clean event system for all interactions
💡

Breaking Changes

v4.0.0 introduces breaking changes in the options structure. See the migration guide below.

Old: clockType: '12h'
New: clock: { type: '12h' }

Migration Guide

Option Mapping

v3.xv4.0.0
clockTypeclock.type
themeui.theme
mobileui.mobile
animationui.animation
okLabellabels.ok
cancelLabellabels.cancel
incrementMinutesclock.incrementMinutes
focusTrapbehavior.focusTrap

Complete Migration Example

// v3.x
const picker = new TimepickerUI(input, {
  clockType: '24h',
  theme: 'dark',
  mobile: true,
  animation: true,
  incrementMinutes: 15,
  okLabel: 'Confirm',
  cancelLabel: 'Close',
  focusTrap: true
});


// v4.0.0
const picker = new TimepickerUI(input, {
  clock: {
    type: '24h',
    incrementMinutes: 15
  },
  ui: {
    theme: 'dark',
    mobile: true,
    animation: true
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close'
  },
  behavior: {
    focusTrap: true
  }
});

Ready to upgrade?

Check out the full documentation to explore all new features and options.

Installation GuideAPI ReferenceFull Changelog