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

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

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

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

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

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

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)

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

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

v3 (Callbacks - Recommended)

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.

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

// Only destroys picker, keeps input
picker.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)

// 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)

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

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

const picker = new TimepickerUI('#input');

// Get current value
const currentTime = picker.getValue();
console.log(currentTime); // "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.

const picker = new TimepickerUI('#input', {
  inline: {
    enabled: true,
    containerId: 'timepicker-container',
    showButtons: false,
    autoUpdate: true,
  },
});

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

Complete Migration Example

v2 Code

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)

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