timepicker-ui
4.6.0GitHub
timepicker-ui
GitHub4.6.0
Legacy / Migrate to v3

Legacy Migration Guide v2 to v3

Legacy Documentation

Historical guide for upgrading from v2.x to v3.x

Legacy Documentation

This guide is for legacy users migrating from version 2.x to 3.x.

If you're using v3.x and want to upgrade to v4.x, please see the Migration Guide v3 to v4.

Breaking Changes

#

1. CSS Must Be Imported Manually

In v3, CSS is no longer automatically included. You must import it manually.

v2

index.js
// CSS was automatically included
import { TimepickerUI } from 'timepicker-ui';

v3

index.js
// You must import CSS manually
import { TimepickerUI } from 'timepicker-ui';
import 'timepicker-ui/main.css';

2. Event Names Changed

All event names have been prefixed with timepicker: for better namespacing and to avoid conflicts.

v2

index.js
input.addEventListener('show', (e) => {
  console.log('Opened');
});


input.addEventListener('accept', (e) => {
  console.log('Confirmed:', e.detail);
});


input.addEventListener('cancel', (e) => {
  console.log('Cancelled');
});

v3

index.js
input.addEventListener('timepicker:open', (e) => {
  console.log('Opened');
});


input.addEventListener('timepicker:confirm', (e) => {
  console.log('Confirmed:', e.detail);
});


input.addEventListener('timepicker:cancel', (e) => {
  console.log('Cancelled');
});

3. Recommended: Use Callbacks Instead of Events

v3 introduces a new callback-based API which is cleaner and more modern than DOM events.

v2 (DOM Events)

index.js
input.addEventListener('accept', (e) => {
  console.log('Time:', e.detail);
});


input.addEventListener('cancel', () => {
  console.log('Cancelled');
});

v3 (Callbacks - Recommended)

index.js
const picker = new TimepickerUI(input, {
  onConfirm: (data) => {
    console.log('Time:', data);
  },
  onCancel: (data) => {
    console.log('Cancelled');
  },
  onOpen: () => {
    console.log('Opened');
  },
});

4. destroy() Behavior Changed

In v2, destroy() removed the input element from the DOM. In v3, it only destroys the timepicker instance and keeps the input element intact.

v2

index.js
// Removed input from DOM
picker.destroy(); // Input is gone!

v3

index.js
// Only destroys picker, keeps input
picker.destroy(); // Input remains in DOM

Event Name Mapping

#
v2 Eventv3 Event
showtimepicker:open
accepttimepicker:confirm
canceltimepicker:cancel
updatetimepicker:update

New in v3

#
Inline Mode
Display timepicker directly in a container without modal
Instance Management
getById() and destroyAll() methods
Direct Callbacks
Pass callbacks directly in options
5 New Themes
Extended theme options for better customization
getValue() / setValue()
Programmatically get and set time values
Better TypeScript
Improved type definitions and IntelliSense
EventEmitter API
Modern event handling with on(), off(), once()

EventEmitter API (v3.x)

#

Starting in v3.x, we recommend using the new EventEmitter API instead of DOM events. This will become the standard in future versions.

Old Way (Deprecated)

index.js
// DOM events - will be removed in v4
input.addEventListener('timepicker:confirm', (e) => {
  console.log(e.detail);
});


input.addEventListener('timepicker:cancel', (e) => {
  console.log('Cancelled');
});

New Way (Recommended)

index.js
// EventEmitter API - recommended
picker.on('confirm', (data) => {
  console.log(data);
});


picker.on('cancel', (data) => {
  console.log('Cancelled');
});


// One-time listener
picker.once('open', () => {
  console.log('First open only');
});


// Remove listener
const handler = (data) => console.log(data);
picker.on('confirm', handler);
picker.off('confirm', handler);

Benefits

  • Cleaner API without prefixes
  • Better TypeScript support
  • No DOM pollution
  • Memory-efficient (automatic cleanup on destroy)
  • Supports once() for one-time listeners

Instance Management

#

v3 introduces new static methods for managing multiple timepicker instances.

index.js
// Create instances with IDs
const picker1 = new TimepickerUI('#input1', { id: 'picker1' });
const picker2 = new TimepickerUI('#input2', { id: 'picker2' });


// Get instance by ID
const instance = TimepickerUI.getById('picker1');


// Destroy all instances at once
TimepickerUI.destroyAll();

getValue() and setValue()

#

New methods for programmatically getting and setting time values.

index.js
const picker = new TimepickerUI('#input');


// Get current value
const value = picker.getValue();
console.log(value); // "14:30"


// Set new value
picker.setValue('09:15');


// Set value with custom format
picker.setValue('3:45 PM');

Inline Mode

#

Display the timepicker directly in a container without using a modal.

index.js
const picker = new TimepickerUI('#input', {
  inline: {
    enabled: true,
    containerId: 'timepicker-container',
    showButtons: false,
    autoUpdate: true,
  },
});
index.html
<input type="text" id="input" />
<div id="timepicker-container"></div>

In 4.5 this option is ui.inline.container: '#timepicker-container', which takes a selector or an element. See the Migration Guide v3 to v4 for the other option names.

Complete Migration Example

#

v2 Code

index.js
import { TimepickerUI } from 'timepicker-ui';


const input = document.querySelector('#myInput');


// v2 initialization
const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'basic',
});


// v2 events
input.addEventListener('show', () => {
  console.log('Opened');
});


input.addEventListener('accept', (e) => {
  console.log('Time selected:', e.detail);
});


input.addEventListener('cancel', () => {
  console.log('Cancelled');
});

v3 Code (Migrated)

index.js
import { TimepickerUI } from 'timepicker-ui';
import 'timepicker-ui/main.css'; // Required in v3


const input = document.querySelector('#myInput');


// v3 initialization with callbacks
const picker = new TimepickerUI(input, {
  clockType: '12h',
  theme: 'basic',
  // Modern callback-based API
  onOpen: () => {
    console.log('Opened');
  },
  onConfirm: (data) => {
    console.log('Time selected:', data);
  },
  onCancel: () => {
    console.log('Cancelled');
  },
});


// Or use EventEmitter API (recommended)
picker.on('confirm', (data) => {
  console.log('Confirmed:', data);
});


picker.once('open', () => {
  console.log('First open only');
});

Migration Checklist

#
Add CSS import
Import timepicker-ui/main.css in your code
Update event names
Add timepicker: prefix to all event names
Consider using callbacks
Replace DOM events with onConfirm, onCancel, etc.
Check destroy() usage
Verify that input element persistence is correct for your use case
Test thoroughly
Test all timepicker functionality in your application

Next Steps

#

After migrating to v3, consider upgrading to v4 for the latest features and improvements.

View Migration Guide v3 to v4

Esc