Timepicker-UI
Latest Release

What's New

Stay up to date with the latest features and improvements

💡

Version 4.1.1 Released!

February 1, 2026 - Bug fix and quality improvements

What's new:

  • Mobile input validation fix - Invalid time values (e.g., 169:70) now auto-clamp to valid ranges when typing
  • Test coverage - Expanded to 1100+ tests with 90%+ code coverage
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