Skip to content
timepicker-ui
API

Events

Handle timepicker events using EventEmitter API or callbacks

EventEmitter API (Recommended)

The new EventEmitter API provides a clean, type-safe way to handle events:

on(event, handler)

Subscribe to an event. Handler is called every time the event fires.

index.tstypescript
1const picker = new TimepickerUI(input);
2picker.create();
3

4picker.on('confirm', (data) => {
5  console.log('Time confirmed:', data);
6});

once(event, handler)

Subscribe to an event that fires only once.

index.tstypescript
1picker.once('open', () => {
2  console.log('Opened for the first time');
3});

off(event, handler)

Unsubscribe from an event.

index.tstypescript
1const handler = (data) => console.log(data);
2picker.on('confirm', handler);
3picker.off('confirm', handler);

Available Events

All events you can subscribe to. These events work in both clock (default) and wheel mode. A few additional events (range:get-disabled-time, range:update-disabled, range:minute:commit) are internal coordination events and not part of the public contract.

confirm

Triggered when user confirms time selection.

index.tstypescript
1picker.on('confirm', (data) => {
2  console.log('Hour:', data.hour);
3  console.log('Minutes:', data.minutes);
4  console.log('Type:', data.type); // 'AM' or 'PM' (12h mode)
5  console.log('Auto commit:', data.autoCommit);
6  // autoCommit is true when the confirm was triggered
7  // by wheel.commitOnScroll instead of the OK button
8});

cancel

Triggered when user cancels or closes picker. The payload is empty.

index.tstypescript
1picker.on('cancel', () => {
2  console.log('Cancelled');
3});

open

Triggered when picker opens.

index.tstypescript
1picker.on('open', (data) => {
2  console.log('Picker opened');
3  console.log(data.hour, data.minutes, data.type);
4  console.log(data.degreesHours, data.degreesMinutes);
5});

show

Triggered when the modal becomes visible. Empty payload.

index.tstypescript
1picker.on('show', () => {
2  console.log('Modal shown');
3});

hide

Triggered when the modal is hidden. Empty payload.

index.tstypescript
1picker.on('hide', () => {
2  console.log('Modal hidden');
3});

update

Triggered when time value changes during interaction.

index.tstypescript
1picker.on('update', (data) => {
2  console.log('Time updated:', data.hour, data.minutes);
3  console.log('Type:', data.type); // 'AM' or 'PM' (12h mode)
4});

select:hour

Triggered when hour is selected.

index.tstypescript
1picker.on('select:hour', (data) => {
2  console.log('Hour selected:', data.hour);
3});

select:minute

Triggered when minute is selected.

index.tstypescript
1picker.on('select:minute', (data) => {
2  console.log('Minute selected:', data.minutes);
3});

select:am

Triggered when AM is selected (12h mode only).

index.tstypescript
1picker.on('select:am', (data) => {
2  console.log('AM selected');
3});

select:pm

Triggered when PM is selected (12h mode only).

index.tstypescript
1picker.on('select:pm', (data) => {
2  console.log('PM selected');
3});

switch:view

Triggered when switching between clock and keyboard view. Empty payload.

index.tstypescript
1picker.on('switch:view', () => {
2  console.log('View switched');
3});

error

Triggered when validation error occurs.

index.tstypescript
1picker.on('error', (data) => {
2  console.error('Error:', data.error);
3  console.log('Rejected:', data.rejectedHour, data.rejectedMinute);
4  console.log('Input values:', data.inputHour, data.inputMinute);
5  console.log('Input type/length:', data.inputType, data.inputLength);
6});

clear

Triggered when user clicks the clear button.

index.tstypescript
1picker.on('clear', (data) => {
2  console.log('Time cleared. Previous value:', data.previousValue);
3});

timezone:change

Triggered when the timezone is changed (timezone plugin only).

index.tstypescript
1picker.on('timezone:change', (data) => {
2  console.log('Timezone:', data.timezone);
3});

range:confirm

Triggered when a time range is confirmed (range mode only).

index.tstypescript
1picker.on('range:confirm', (data) => {
2  console.log('From:', data.from, 'To:', data.to);
3  console.log('Duration (minutes):', data.duration);
4});

range:switch

Triggered when switching between the from/to segments (range mode only).

index.tstypescript
1picker.on('range:switch', (data) => {
2  console.log('Active segment:', data.active); // 'from' | 'to'
3  console.log('Disabled time:', data.disabledTime);
4});

range:validation

Triggered when the range duration is validated (range mode only).

index.tstypescript
1picker.on('range:validation', (data) => {
2  console.log('Valid:', data.valid, 'Duration:', data.duration);
3  console.log('Limits:', data.minDuration, data.maxDuration);
4});

animation:clock / animation:start / animation:end

Animation coordination events fired around open/close and clock transitions. Empty payloads.

index.tstypescript
1picker.on('animation:start', () => console.log('Animation started'));
2picker.on('animation:end', () => console.log('Animation finished'));
3picker.on('animation:clock', () => console.log('Clock animation'));

wheel:scroll:start

Triggered when a wheel column starts scrolling (wheel mode only).

index.tstypescript
1picker.on('wheel:scroll:start', (data) => {
2  console.log('Scroll started on column:', data.column);
3  // data.column: 'hours' | 'minutes' | 'ampm'
4});

wheel:scroll:end

Triggered when a wheel column finishes scrolling and snaps to a value (wheel mode only).

index.tstypescript
1picker.on('wheel:scroll:end', (data) => {
2  console.log('Column:', data.column, 'snapped to:', data.value);
3  console.log('Previous value:', data.previousValue);
4  // data.column: 'hours' | 'minutes' | 'ampm'
5});

Callback Options (Alternative)

You can also use callback options in the constructor:

onConfirm

Alternative: pass callback in options.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onConfirm: (data) => {
4      console.log('Confirmed:', data);
5    }
6  }
7});

onCancel

Triggered when user cancels.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onCancel: (data) => {
4      console.log('Cancelled');
5    }
6  }
7});

onOpen

Triggered when picker opens.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onOpen: () => {
4      console.log('Opened');
5    }
6  }
7});

onUpdate

Triggered during time changes.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onUpdate: (data) => {
4      console.log('Updated:', data);
5    }
6  }
7});

onSelectHour

Triggered when hour is selected.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onSelectHour: (data) => {
4      console.log('Hour:', data.hour);
5    }
6  }
7});

onSelectMinute

Triggered when minute is selected.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onSelectMinute: (data) => {
4      console.log('Minute:', data.minutes);
5    }
6  }
7});

onSelectAM

Triggered when AM is selected.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onSelectAM: () => {
4      console.log('AM selected');
5    }
6  }
7});

onSelectPM

Triggered when PM is selected.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onSelectPM: () => {
4      console.log('PM selected');
5    }
6  }
7});

onError

Triggered on validation error.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onError: (data) => {
4      console.error('Error:', data.error);
5    }
6  }
7});

onTimezoneChange

Triggered when timezone is changed (timezone plugin only).

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onTimezoneChange: (data) => {
4      console.log('Timezone:', data.timezone);
5    }
6  }
7});

onRangeConfirm

Triggered when a range is confirmed (range mode only).

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onRangeConfirm: (data) => {
4      console.log('Range:', data.from, '-', data.to, data.duration);
5    }
6  }
7});

onRangeSwitch

Triggered when switching between from/to segments (range mode only).

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onRangeSwitch: (data) => {
4      console.log('Active segment:', data.active);
5    }
6  }
7});

onRangeValidation

Triggered on range validation (range mode only).

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onRangeValidation: (data) => {
4      console.log('Valid:', data.valid, 'Duration:', data.duration);
5    }
6  }
7});

onClear

Triggered when user clicks the clear button.

index.tstypescript
1new TimepickerUI(input, {
2  callbacks: {
3    onClear: (data) => {
4      console.log('Cleared:', data.previousValue);
5    }
6  }
7});

Legacy DOM Events (Removed)

Removed in v4.0.0

DOM events (e.g., timepicker:confirm) have been removed in v4.0.0. If you're upgrading from v3.x, you must migrate to the EventEmitter API.

The EventEmitter API provides better type safety, error handling, and performance.

index.tstypescript
1// REMOVED in v4.0.0
2input.addEventListener('timepicker:confirm', (e) => {
3  console.log(e.detail);
4});
5

6// CORRECT - use the EventEmitter API instead
7picker.on('confirm', (data) => {
8  console.log(data);
9});

Event Data

Every event has its own payload type, exported from timepicker-ui. The most important ones:

index.tstypescript
1type OpenEventData = {
2  hour: string;
3  minutes: string;
4  type?: string;                 // 'AM' or 'PM' (12h mode)
5  degreesHours: number | null;
6  degreesMinutes: number | null;
7};
8

9type ConfirmEventData = {
10  hour?: string;
11  minutes?: string;
12  type?: string;
13  autoCommit?: boolean;          // true when triggered by wheel.commitOnScroll
14};
15

16type UpdateEventData = {
17  hour?: string;
18  minutes?: string;
19  type?: string;
20};
21

22type CancelEventData = Record<string, never>;  // empty payload
23

24type ClearEventData = {
25  previousValue: string | null;
26};
27

28type ErrorEventData = {
29  error: string;
30  rejectedHour?: string;
31  rejectedMinute?: string;
32  inputHour?: string | number;
33  inputMinute?: string | number;
34  inputType?: string;
35  inputLength?: string | number;
36};
37

38// Also exported: SelectHourEventData, SelectMinuteEventData,
39// SelectAMEventData, SelectPMEventData, ShowEventData, HideEventData,
40// SwitchViewEventData, TimezoneChangeEventData, RangeConfirmEventData,
41// RangeSwitchEventData, RangeValidationEventData,
42// WheelScrollStartEventData, WheelScrollEndEventData

Complete Example

index.tstypescript
1const picker = new TimepickerUI(input, {
2  ui: { theme: 'dark' },
3  clock: { type: '12h' }
4});
5picker.create();
6

7// EventEmitter API (recommended)
8picker.on('confirm', (data) => {
9  console.log('Time confirmed:', data.hour, data.minutes, data.type);
10  fetch('/api/save-time', {
11    method: 'POST',
12    body: JSON.stringify(data)
13  });
14});
15

16picker.on('cancel', () => {
17  console.log('User cancelled');
18});
19

20picker.on('update', (data) => {
21  document.getElementById('display').textContent = 
22    `${data.hour}:${data.minutes} ${data.type || ''}`;
23});
24

25picker.on('select:hour', (data) => {
26  console.log('Hour selected:', data.hour);
27});
28

29picker.on('select:minute', (data) => {
30  console.log('Minute selected:', data.minutes);
31});
32

33picker.on('error', (data) => {
34  console.error('Validation error:', data.error);
35});
36

37// One-time event
38picker.once('open', () => {
39  console.log('Picker opened for the first time');
40});
41

42// Remove event listener
43const updateHandler = (data) => console.log(data);
44picker.on('update', updateHandler);
45picker.off('update', updateHandler);