GuideLegacy Documentation

Legacy Migration Guide v2 to v3

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.javascriptjavascript

1// CSS was automatically included
2import { TimepickerUI } from 'timepicker-ui';

v3

index.javascriptjavascript

1// You must import CSS manually
2import { TimepickerUI } from 'timepicker-ui';
3import '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.javascriptjavascript

1input.addEventListener('show', (e) => {
2  console.log('Opened');
3});
4
5input.addEventListener('accept', (e) => {
6  console.log('Confirmed:', e.detail);
7});
8
9input.addEventListener('cancel', (e) => {
10  console.log('Cancelled');
11});

v3

index.javascriptjavascript

1input.addEventListener('timepicker:open', (e) => {
2  console.log('Opened');
3});
4
5input.addEventListener('timepicker:confirm', (e) => {
6  console.log('Confirmed:', e.detail);
7});
8
9input.addEventListener('timepicker:cancel', (e) => {
10  console.log('Cancelled');
11});

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.javascriptjavascript

1input.addEventListener('accept', (e) => {
2  console.log('Time:', e.detail);
3});
4
5input.addEventListener('cancel', () => {
6  console.log('Cancelled');
7});

v3 (Callbacks - Recommended)

index.javascriptjavascript

1const picker = new TimepickerUI(input, {
2  onConfirm: (data) => {
3    console.log('Time:', data);
4  },
5  onCancel: (data) => {
6    console.log('Cancelled');
7  },
8  onOpen: () => {
9    console.log('Opened');
10  },
11});

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.javascriptjavascript

1// Removed input from DOM
2picker.destroy(); // Input is gone!

v3

index.javascriptjavascript

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

Event Name Mapping

v2 Event	v3 Event
show	timepicker:open
accept	timepicker:confirm
cancel	timepicker:cancel
update	timepicker: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.javascriptjavascript

1// DOM events - will be removed in v4
2input.addEventListener('timepicker:confirm', (e) => {
3  console.log(e.detail);
4});
5
6input.addEventListener('timepicker:cancel', (e) => {
7  console.log('Cancelled');
8});

New Way (Recommended)

index.javascriptjavascript

1// EventEmitter API - recommended
2picker.on('confirm', (data) => {
3  console.log(data);
4});
5
6picker.on('cancel', (data) => {
7  console.log('Cancelled');
8});
9
10// One-time listener
11picker.once('open', () => {
12  console.log('First open only');
13});
14
15// Remove listener
16const handler = (data) => console.log(data);
17picker.on('confirm', handler);
18picker.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.javascriptjavascript

1// Create instances with IDs
2const picker1 = new TimepickerUI('#input1', { id: 'picker1' });
3const picker2 = new TimepickerUI('#input2', { id: 'picker2' });
4
5// Get instance by ID
6const instance = TimepickerUI.getById('picker1');
7
8// Destroy all instances at once
9TimepickerUI.destroyAll();

getValue() and setValue()

New methods for programmatically getting and setting time values.

index.javascriptjavascript

1const picker = new TimepickerUI('#input');
2
3// Get current value
4const currentTime = picker.getValue();
5console.log(currentTime); // "14:30"
6
7// Set new value
8picker.setValue('09:15');
9
10// Set value with custom format
11picker.setValue('3:45 PM');

Inline Mode

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

index.javascriptjavascript

1const picker = new TimepickerUI('#input', {
2  inline: {
3    enabled: true,
4    containerId: 'timepicker-container',
5    showButtons: false,
6    autoUpdate: true,
7  },
8});

index.htmlhtml

1<input type="text" id="input" />
2<div id="timepicker-container"></div>

Complete Migration Example

v2 Code

index.javascriptjavascript

1import { TimepickerUI } from 'timepicker-ui';
2
3const input = document.querySelector('#myInput');
4
5// v2 initialization
6const picker = new TimepickerUI(input, {
7  clockType: '12h',
8  theme: 'basic',
9});
10
11// v2 events
12input.addEventListener('show', () => {
13  console.log('Opened');
14});
15
16input.addEventListener('accept', (e) => {
17  console.log('Time selected:', e.detail);
18});
19
20input.addEventListener('cancel', () => {
21  console.log('Cancelled');
22});

v3 Code (Migrated)

index.javascriptjavascript

1import { TimepickerUI } from 'timepicker-ui';
2import 'timepicker-ui/main.css'; // Required in v3
3
4const input = document.querySelector('#myInput');
5
6// v3 initialization with callbacks
7const picker = new TimepickerUI(input, {
8  clockType: '12h',
9  theme: 'basic',
10  // Modern callback-based API
11  onOpen: () => {
12    console.log('Opened');
13  },
14  onConfirm: (data) => {
15    console.log('Time selected:', data);
16  },
17  onCancel: () => {
18    console.log('Cancelled');
19  },
20});
21
22// Or use EventEmitter API (recommended)
23picker.on('confirm', (data) => {
24  console.log('Confirmed:', data);
25});
26
27picker.once('open', () => {
28  console.log('First open only');
29});

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