API

TypeScript

Full TypeScript support with type definitions

Installation

TypeScript definitions are included with the package:

index.tstypescript

1npm install timepicker-ui
2
3// Types are automatically available
4import { TimepickerUI } from 'timepicker-ui';
5import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';

Main Interfaces

`TimepickerOptions`

The grouped options object (v4.0.0+). Each group has its own exported interface: ClockOptions, UIOptions, LabelsOptions, BehaviorOptions, CallbacksOptions, TimezoneOptions, RangeOptions, WheelOptions, ClearBehaviorOptions.

index.tstypescript

1interface TimepickerOptions {
2  clock?: ClockOptions;          // type, increments, disabledTime, currentTime, ...
3  ui?: UIOptions;                // theme, mode, animation, backdrop, inline, ...
4  labels?: LabelsOptions;        // all UI text and accessibility labels
5  behavior?: BehaviorOptions;    // focusTrap, focusInputAfterClose, delayHandler, id
6  callbacks?: CallbacksOptions;  // onConfirm, onCancel, onOpen, onUpdate, ...
7  timezone?: TimezoneOptions;    // timezone plugin config
8  range?: RangeOptions;          // range plugin config
9  wheel?: WheelOptions;          // wheel / compact-wheel mode config
10  clearBehavior?: ClearBehaviorOptions; // clear button behavior
11}
12
13// All group interfaces are exported:
14import type {
15  TimepickerOptions,
16  ClockOptions,
17  UIOptions,
18  LabelsOptions,
19  BehaviorOptions,
20  CallbacksOptions,
21  TimezoneOptions,
22  RangeOptions,
23  WheelOptions,
24  ClearBehaviorOptions,
25} from 'timepicker-ui';

`Event data types`

Each event/callback has its own payload type. All of them are exported from 'timepicker-ui'.

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

`TimepickerEventMap`

Maps every event name to its payload type. picker.on / once / off are typed against this map, so handlers get the correct payload type automatically.

index.tstypescript

1import type { TimepickerEventMap } from 'timepicker-ui';
2
3interface TimepickerEventMap {
4  open: OpenEventData;
5  cancel: CancelEventData;
6  confirm: ConfirmEventData;
7  clear: ClearEventData;
8  show: ShowEventData;
9  hide: HideEventData;
10  update: UpdateEventData;
11  'select:hour': SelectHourEventData;
12  'select:minute': SelectMinuteEventData;
13  'select:am': SelectAMEventData;
14  'select:pm': SelectPMEventData;
15  'switch:view': SwitchViewEventData;
16  'timezone:change': TimezoneChangeEventData;
17  'range:confirm': RangeConfirmEventData;
18  'range:switch': RangeSwitchEventData;
19  'range:validation': RangeValidationEventData;
20  'wheel:scroll:start': WheelScrollStartEventData;
21  'wheel:scroll:end': WheelScrollEndEventData;
22  error: ErrorEventData;
23  // ...plus internal animation/range coordination events
24}

`Inline mode shape (ui.inline)`

Inline configuration shape, defined inline on UIOptions (not a separately exported type):

index.tstypescript

1ui: {
2  inline?: {
3    enabled: boolean;
4    containerId: string;
5    showButtons?: boolean;
6    autoUpdate?: boolean;
7  };
8}

`Disabled time shape (clock.disabledTime)`

Disabled time configuration shape, defined inline on ClockOptions:

index.tstypescript

1clock: {
2  disabledTime?: {
3    hours?: Array<string | number>;
4    minutes?: Array<string | number>;
5    interval?: string | string[];   // e.g. "10:00 AM - 12:00 PM"
6  };
7}

`Current time shape (clock.currentTime)`

Current time configuration shape, defined inline on ClockOptions:

index.tstypescript

1clock: {
2  currentTime?:
3    | {
4        time?: Date;
5        updateInput?: boolean;
6        locales?: string | string[];
7        preventClockType?: boolean;
8      }
9    | boolean;
10}

Inline Unions

`ui.theme`

Available theme names. The union is defined inline on UIOptions (the library does not export a separate Theme alias).

index.tstypescript

1theme?:
2  | 'basic'
3  | 'crane'
4  | 'crane-straight'
5  | 'm2'
6  | 'm3-green'
7  | 'dark'
8  | 'glassmorphic'
9  | 'pastel'
10  | 'ai'
11  | 'cyberpunk'
12  | 'blueprint'
13  | 'blueprint-dark';

`clock.type`

Clock format, defined inline on ClockOptions (no exported ClockType alias).

index.tstypescript

type?: '12h' | '24h';

Usage Examples

Basic TypeScript Usage

index.tstypescript

1import { TimepickerUI } from 'timepicker-ui';
2import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';
3
4const options: TimepickerOptions = {
5  ui: { theme: 'dark' },
6  clock: { type: '24h' },
7  callbacks: {
8    onConfirm: (data: ConfirmEventData) => {
9      console.log(`Time: ${data.hour}:${data.minutes}`);
10    }
11  }
12};
13
14const input = document.querySelector<HTMLInputElement>('#timepicker');
15if (input) {
16  const picker = new TimepickerUI(input, options);
17  picker.create();
18}

Typed Event Subscriptions

index.tstypescript

1import { TimepickerUI } from 'timepicker-ui';
2
3const picker = new TimepickerUI('#timepicker');
4picker.create();
5
6// picker.on is typed against TimepickerEventMap -
7// the handler payload type is inferred from the event name
8picker.on('confirm', (data) => {
9  // data: ConfirmEventData
10  console.log(data.hour, data.minutes, data.type, data.autoCommit);
11});
12
13picker.on('update', (data) => {
14  // data: UpdateEventData
15  console.log(data.hour, data.minutes, data.type);
16});
17
18picker.on('error', (data) => {
19  // data: ErrorEventData
20  console.error(data.error, data.rejectedHour, data.rejectedMinute);
21});
22
23picker.once('open', (data) => {
24  // data: OpenEventData
25  console.log(data.degreesHours, data.degreesMinutes);
26});

React with TypeScript

index.tsxtsx

1import { useEffect, useRef } from 'react';
2import { TimepickerUI } from 'timepicker-ui';
3import type { TimepickerOptions } from 'timepicker-ui';
4
5interface TimePickerProps {
6  onTimeSelect?: (time: string) => void;
7  theme?: 'basic' | 'dark' | 'cyberpunk';
8}
9
10export function TimePicker({ onTimeSelect, theme = 'basic' }: TimePickerProps) {
11  const inputRef = useRef<HTMLInputElement>(null);
12
13  useEffect(() => {
14    if (!inputRef.current) return;
15
16    const options: TimepickerOptions = {
17      ui: { theme },
18      callbacks: {
19        onConfirm: (data) => {
20          if (onTimeSelect && data.hour && data.minutes) {
21            const time = `${data.hour}:${data.minutes}`;
22            onTimeSelect(time);
23          }
24        }
25      }
26    };
27
28    const picker = new TimepickerUI(inputRef.current, options);
29    picker.create();
30
31    return () => picker.destroy();
32  }, [theme, onTimeSelect]);
33
34  return <input ref={inputRef} type="text" placeholder="Select time" />;
35}

Error Handling

index.tstypescript

1import type { ConfirmEventData, ErrorEventData } from 'timepicker-ui';
2import { TimepickerUI } from 'timepicker-ui';
3
4const picker = new TimepickerUI('#timepicker', {
5  callbacks: {
6    onError: (data: ErrorEventData) => {
7      console.error('Timepicker error:', data.error);
8      alert(`Invalid time format: ${data.error}`);
9    },
10    onConfirm: (data: ConfirmEventData) => {
11      console.log('Time confirmed:', `${data.hour}:${data.minutes}`);
12    }
13  }
14});

Extending Types

index.tstypescript

1import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui';
2import { TimepickerUI } from 'timepicker-ui';
3
4// Extend options with custom properties
5interface CustomTimepickerOptions extends TimepickerOptions {
6  analyticsEnabled?: boolean;
7}
8
9// Create wrapper with custom logic
10class CustomTimepicker {
11  private picker: TimepickerUI;
12  private analyticsEnabled: boolean;
13
14  constructor(
15    input: HTMLInputElement,
16    options: CustomTimepickerOptions
17  ) {
18    const { analyticsEnabled, ...pickerOptions } = options;
19    this.analyticsEnabled = analyticsEnabled ?? false;
20
21    const finalOptions: TimepickerOptions = {
22      ...pickerOptions,
23      callbacks: {
24        ...pickerOptions.callbacks,
25        onConfirm: (data: ConfirmEventData) => {
26          if (this.analyticsEnabled) {
27            this.trackEvent('time_confirmed', data);
28          }
29          pickerOptions.callbacks?.onConfirm?.(data);
30        }
31      }
32    };
33
34    this.picker = new TimepickerUI(input, finalOptions);
35  }
36
37  private trackEvent(event: string, data: ConfirmEventData) {
38    console.log('Analytics:', event, data);
39  }
40
41  create() {
42    this.picker.create();
43  }
44
45  destroy() {
46    this.picker.destroy();
47  }
48}

IntelliSense Support

All options and methods have full IntelliSense support in VS Code and other TypeScript-aware editors. Hover over any property to see its documentation.