Breaking Changes

Migration Guide v3 to v4

Complete guide for upgrading from v3.x to v4.0.0

💡

Important Notice

Version 4.0.0 introduces breaking changes in the options structure. There is NO backward compatibility - all v3.x code will break and must be updated.

Migration typically takes 15-60 minutes depending on your codebase size.

💡

Migrating from v2.x?

If you're still using version 2.x, please see the Legacy Migration Guide v2 to v3 first, then follow this guide to upgrade to v4.

What Changed?

The previous flat structure with 40+ fields has been reorganized into 5 logical groups to improve code clarity, maintainability, and developer experience:

clock

Clock behavior configuration

ui

UI appearance and behavior

labels

Text labels customization

behavior

General behavior settings

callbacks

Event handler callbacks

Before & After

Old API (v3.x) - Flat Structure

const timepicker = new TimepickerUI('#input', {
  clockType: '12h',
  amLabel: 'AM',
  pmLabel: 'PM',
  okLabel: 'OK',
  cancelLabel: 'Cancel',
  timeLabel: 'Select time',
  animation: true,
  backdrop: true,
  theme: 'basic',
  incrementHours: 1,
  incrementMinutes: 5,
  focusTrap: true,
  delayHandler: 300,
  mobile: false,
  editable: false,
  onOpen: (event) => console.log('opened', event),
  onConfirm: (event) => console.log('confirmed', event),
});

New API (v4.0.0) - Grouped Structure

const timepicker = new TimepickerUI('#input', {
  clock: {
    type: '12h',
    incrementHours: 1,
    incrementMinutes: 5,
  },
  ui: {
    animation: true,
    backdrop: true,
    theme: 'basic',
    mobile: false,
    editable: false,
  },
  labels: {
    am: 'AM',
    pm: 'PM',
    ok: 'OK',
    cancel: 'Cancel',
    time: 'Select time',
  },
  behavior: {
    focusTrap: true,
    delayHandler: 300,
  },
  callbacks: {
    onOpen: (event) => console.log('opened', event),
    onConfirm: (event) => console.log('confirmed', event),
  },
});

Complete Field Mapping

Clock Options

v3.x (Flat)	v4.0.0 (Grouped)
clockType	clock.type
incrementHours	clock.incrementHours
incrementMinutes	clock.incrementMinutes
autoSwitchToMinutes	clock.autoSwitchToMinutes
disabledTime	clock.disabledTime
currentTime	clock.currentTime

UI Options

v3.x (Flat)	v4.0.0 (Grouped)
theme	ui.theme
animation	ui.animation
backdrop	ui.backdrop
mobile	ui.mobile
enableSwitchIcon	ui.enableSwitchIcon
editable	ui.editable
enableScrollbar	ui.enableScrollbar
cssClass	ui.cssClass
appendModalSelector	ui.appendModalSelector
iconTemplate	ui.iconTemplate
iconTemplateMobile	ui.iconTemplateMobile
inline	ui.inline

Label Options

v3.x (Flat)	v4.0.0 (Grouped)
amLabel	labels.am
pmLabel	labels.pm
okLabel	labels.ok
cancelLabel	labels.cancel
timeLabel	labels.time
mobileTimeLabel	labels.mobileTime
hourMobileLabel	labels.mobileHour
minuteMobileLabel	labels.mobileMinute

Behavior Options

v3.x (Flat)	v4.0.0 (Grouped)
focusInputAfterCloseModal	behavior.focusInputAfterClose
focusTrap	behavior.focusTrap
delayHandler	behavior.delayHandler
id	behavior.id

Callback Options

v3.x (Flat)	v4.0.0 (Grouped)
onOpen	callbacks.onOpen
onCancel	callbacks.onCancel
onConfirm	callbacks.onConfirm
onUpdate	callbacks.onUpdate
onSelectHour	callbacks.onSelectHour
onSelectMinute	callbacks.onSelectMinute
onSelectAM	callbacks.onSelectAM
onSelectPM	callbacks.onSelectPM
onError	callbacks.onError

Accessing & Updating Options

Accessing Options in Code

v3.x

const options = timepicker.options;
console.log(options.clockType); // '12h'
console.log(options.amLabel); // 'AM'

v4.0.0

const options = timepicker.options;
console.log(options.clock.type); // '12h'
console.log(options.labels.am); // 'AM'

Updating Options

❌ v3.x - NO LONGER WORKS

timepicker.update({
  options: {
    clockType: '24h',
    animation: false,
  },
});

✅ v4.0.0 - REQUIRED

timepicker.update({
  options: {
    clock: { type: '24h' },
    ui: { animation: false },
  },
});

TypeScript Support

Version 4.0.0 provides improved TypeScript types for the new grouped structure:

import type {
  TimepickerOptions,   // Main grouped options type
  ClockOptions,        // Clock group
  UIOptions,           // UI group
  LabelsOptions,       // Labels group
  BehaviorOptions,     // Behavior group
  CallbacksOptions,    // Callbacks group
} from 'timepicker-ui';

const options: TimepickerOptions = {
  clock: {
    type: '12h',
    incrementMinutes: 5,
  },
  ui: {
    theme: 'basic',
    animation: true,
  },
  labels: {
    ok: 'Confirm',
    cancel: 'Close',
  },
};

const timepicker = new TimepickerUI('#input', options);

💡

Note: OptionTypes Removed

OptionTypes has been removed. Use TimepickerOptions instead.

Benefits of the New Structure

Better Organization

Related options are grouped together logically

Improved Discoverability

Easier to find related settings

Enhanced IntelliSense

Better autocomplete by category

Reduced Cognitive Load

Smaller, focused option groups

Future-Proof

Easier to add new options without cluttering

Cleaner API

No more 40+ flat fields to navigate

Common Migration Examples

Basic Setup

// v4.0.0
const timepicker = new TimepickerUI('#input', {
  clock: { type: '12h' },
});

Advanced Setup

// v4.0.0
const timepicker = new TimepickerUI('#input', {
  clock: {
    type: '24h',
    incrementMinutes: 15,
    disabledTime: {
      hours: [0, 1, 2, 23],
      interval: ['00:00 - 06:00', '22:00 - 23:59'],
    },
  },
  ui: {
    theme: 'm3-green',
    animation: true,
    backdrop: true,
    mobile: false,
    editable: true,
  },
  labels: {
    time: 'Pick a time',
    ok: 'Confirm',
    cancel: 'Dismiss',
  },
  behavior: {
    focusTrap: true,
    delayHandler: 300,
    focusInputAfterClose: true,
  },
  callbacks: {
    onOpen: () => console.log('Opened'),
    onConfirm: (data) => console.log('Time selected:', data),
    onCancel: () => console.log('Cancelled'),
  },
});

Inline Mode

// v4.0.0
const timepicker = new TimepickerUI('#input', {
  ui: {
    inline: {
      enabled: true,
      containerId: 'timepicker-container',
      showButtons: false,
      autoUpdate: true,
    },
  },
  behavior: {
    focusTrap: false, // Automatically set if not specified
  },
});

FAQ

Will my v3.x code break?

Yes. v4.0.0 is a major breaking change. You MUST update all code to use grouped options.

Is there a migration layer?

No. There is NO backward compatibility. All old flat structure code will break.

Can I mix flat and grouped structures?

No. Only grouped structure is supported in v4.0.0.

How long will migration take?

Depending on your codebase size, it should take 15-60 minutes using find-and-replace.

Need Help?

If you encounter issues during migration: