TypeScript

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

1interface TimepickerOptions {
2  clock?: ClockOptions;          // type, increments, showSeconds, disabledTime, defaultTime, ...
3  ui?: UIOptions;                // theme, mode, animation, backdrop, inline, clearButton, ...
4  labels?: LabelsOptions;        // all UI text and accessibility labels
5  behavior?: BehaviorOptions;    // focusTrap, returnFocus, 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; // deprecated, use ui.clearButton
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';

1type OpenEventData = {
2  hour: string;
3  minutes: string;
4  seconds?: string;              // showSeconds
5  type?: string;                 // 'AM' or 'PM' (12h mode)
6  degreesHours: number | null;   // deprecated, removed in 5.0
7  degreesMinutes: number | null; // deprecated, removed in 5.0
8};
9
10type ConfirmEventData = {
11  hour?: string;
12  minutes?: string;
13  seconds?: string;              // showSeconds
14  type?: string;
15  autoCommit?: boolean;          // true when triggered by wheel.commitOnScroll
16};
17
18type UpdateEventData = {
19  hour?: string;
20  minutes?: string;
21  seconds?: string;              // showSeconds
22  type?: string;
23};
24
25type SelectSecondEventData = {   // payload of 'select:second'
26  seconds: string;
27};
28
29type SelectPeriodEventData = {   // payload of 'select:period'
30  type: 'AM' | 'PM';
31};
32
33type SwitchFaceEventData = {     // payload of 'switch:face'
34  face: 'hours' | 'minutes' | 'seconds';
35};
36
37type CancelEventData = Record<string, never>;   // empty payload
38
39type ClearEventData = {
40  previousValue: string | null;
41};
42
43type ErrorEventData = {
44  error: string;
45  rejectedHour?: string;         // deprecated, always undefined
46  rejectedMinute?: string;       // deprecated, always undefined
47  inputHour?: string | number;
48  inputMinute?: string | number;
49  inputSecond?: string | number; // showSeconds
50  inputType?: string;
51  inputLength?: string | number;
52};
53
54type RangeConfirmEventData = {
55  from: string;
56  to: string;
57  duration: number;              // whole minutes
58  durationSeconds?: number;      // showSeconds, exact length in seconds
59  autoCommit?: boolean;          // true when triggered by wheel.commitOnScroll
60};
61
62type RangeValidationEventData = {
63  valid: boolean;
64  duration: number;              // whole minutes
65  durationSeconds?: number;      // showSeconds, exact length in seconds
66  minDuration?: number;
67  maxDuration?: number;
68};
69
70type WheelScrollEndEventData = {
71  column: 'hours' | 'minutes' | 'seconds' | 'ampm';
72  value: string;
73  previousValue: string | null;
74};
75
76// Also exported: SelectHourEventData, SelectMinuteEventData,
77// SelectAMEventData and SelectPMEventData (deprecated), ShowEventData,
78// HideEventData (deprecated),
79// TimezoneChangeEventData, RangeSwitchEventData,
80// WheelScrollStartEventData
81
82type SwitchViewEventData = {     // payload of 'switch:view'
83  view: TimepickerView;
84};
85
86type RangeChangeEventData = {    // payload of 'range:change'
87  part: 'from' | 'to';
88  from: RangeTimeValue | null;
89  to: RangeTimeValue | null;
90};

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;           // deprecated, never emitted
10  update: UpdateEventData;
11  'select:hour': SelectHourEventData;
12  'select:minute': SelectMinuteEventData;
13  'select:second': SelectSecondEventData;
14  'select:period': SelectPeriodEventData;
15  'select:am': SelectAMEventData;   // deprecated, use 'select:period'
16  'select:pm': SelectPMEventData;   // deprecated, use 'select:period'
17  'switch:face': SwitchFaceEventData;
18  'switch:view': SwitchViewEventData;
19  'timezone:change': TimezoneChangeEventData;
20  'range:confirm': RangeConfirmEventData;
21  'range:switch': RangeSwitchEventData;
22  'range:validation': RangeValidationEventData;
23  'range:change': RangeChangeEventData;   // new in 4.7.0
24  'wheel:scroll:start': WheelScrollStartEventData;
25  'wheel:scroll:end': WheelScrollEndEventData;
26  error: ErrorEventData;
27  // ...plus internal animation/range coordination events
28}

1{
2  hour: string;
3  minutes: string;
4  seconds?: string;              // showSeconds
5  type?: string;                 // 'AM' or 'PM' (12h mode)
6  time: string;                  // '14:30', '02:30 PM', '14:30:15', '02:30:15 PM'
7  degreesHours: number | null;   // deprecated, removed in 5.0
8  degreesMinutes: number | null; // deprecated, removed in 5.0
9}

1ui: {
2  inline?: {
3    enabled: boolean;
4    container?: string | HTMLElement; // required when enabled is true
5    containerId?: string;             // deprecated, use container
6    showButtons?: boolean;
7    autoUpdate?: boolean;
8    embedded?: boolean;               // part of a host component, default false
9    showTitle?: boolean;              // default true, new in 4.7.0
10  };
11}

1import type { TimeOfDay } from 'timepicker-ui';
2
3interface TimeOfDay {
4  hour: number;
5  minutes: number;
6  seconds: number;
7}
8
9const isTimeDisabled = ({ hour }: TimeOfDay): boolean => hour < 9 || hour >= 17;

1import type { RangeTimeValue, RangeTimeState } from 'timepicker-ui';
2
3interface RangeTimeValue {
4  hour: string;
5  minutes: string;
6  seconds?: string;              // showSeconds
7  type?: string;                 // 'AM' or 'PM' (12h mode)
8}
9
10interface RangeTimeState {
11  from: RangeTimeValue | null;
12  to: RangeTimeValue | null;
13}
14
15const range: RangeTimeState | null = picker.getRange();

1import type { TimepickerView } from 'timepicker-ui';
2
3type TimepickerView = 'clock' | 'keyboard';

1import type { RangeTimeInput, RangeCaptionInput } from 'timepicker-ui';
2
3interface RangeTimeInput {
4  from?: string | null;   // setValue() format: '09:00', '9:00 AM'
5  to?: string | null;
6}
7
8interface RangeCaptionInput {
9  from?: string | null;   // plain text under the tab label
10  to?: string | null;
11}
12
13picker.setRange({ from: '09:00' });
14picker.setRangeCaptions({ from: 'Wed Oct 21', to: null });

1import type { RangeChangeEventData } from 'timepicker-ui';
2
3interface RangeChangeEventData {
4  part: 'from' | 'to';          // the end that changed
5  from: RangeTimeValue | null;  // both ends after the change
6  to: RangeTimeValue | null;
7}

1import type {
2  TimeValue,
3  TimeFormatOptions,
4  DisabledTimeCheckOptions
5} from 'timepicker-ui';
6
7interface TimeValue {
8  hour: string;
9  minutes: string;
10  seconds?: string;              // showSeconds
11  type?: string;                 // 'AM' or 'PM' (12h mode)
12}
13
14interface TimeFormatOptions {
15  clockType?: '12h' | '24h';     // default '12h'
16  showSeconds?: boolean;         // default false
17}
18
19type DisabledTimeCheckOptions = Pick<
20  ClockOptions,
21  'type' | 'disabledTime' | 'isTimeDisabled' | 'showSeconds'
22>;

1import type { TimepickerEventName, TimepickerEventMap } from 'timepicker-ui';
2
3function listen<K extends TimepickerEventName>(
4  picker: TimepickerUI,
5  name: K,
6  handler: (data: TimepickerEventMap[K]) => void
7) {
8  return picker.on(name, handler);
9}
10
11listen(picker, 'range:change', (data) => console.log(data.part));

1import type { PluginManager, PluginTimeView } from 'timepicker-ui';
2
3interface PluginTimeView {
4  show(value: { hour: string; minutes: string; seconds?: string; type?: string }): void;
5}
6
7interface PluginManager {
8  init(): void;
9  destroy(): void;
10  attachPopover?(): void;
11  detachPopover?(): void;
12  scrollToValue?(hour: string, minute: string, type?: string, second?: string): void;
13  getSelection?(): { hour: string; minutes: string; seconds?: string; type?: string } | null;
14  setTimeView?(view: PluginTimeView): void;   // new in 4.7.0
15}

1import {
2  getTimezoneList,
3  DEFAULT_TIMEZONES,
4  type TimezoneInfo
5} from 'timepicker-ui/plugins/timezone';
6
7interface TimezoneInfo {
8  readonly id: string;       // 'Asia/Tokyo'
9  readonly label: string;    // 'Tokyo (+09:00)'
10  readonly offset: string;   // '+09:00'
11}
12
13const DEFAULT_TIMEZONES: readonly string[];
14
15function getTimezoneList(list?: readonly string[]): TimezoneInfo[];
16
17const zones = getTimezoneList([...DEFAULT_TIMEZONES, 'Europe/Warsaw']);

1clock: {
2  disabledTime?: {
3    hours?: Array<string | number>;
4    minutes?: Array<string | number>;
5    seconds?: Array<string | number>; // used with showSeconds
6    ranges?: string | string[];       // e.g. "10:00 AM - 12:00 PM", "10:00:30 AM - 10:05 AM"
7    interval?: string | string[];     // deprecated, use ranges
8  };
9  isTimeDisabled?: (time: TimeOfDay) => boolean;  // union with disabledTime
10}

1clock: {
2  defaultTime?:
3    | 'now'
4    | {
5        time?: Date | 'now';
6        updateInput?: boolean;
7      };
8}

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';

type?: '12h' | '24h' | 'auto';   // 'auto' follows the browser locale

incrementSeconds?: 1 | 5 | 10 | 15 | 20 | 30;

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}

1import { TimepickerUI } from 'timepicker-ui';
2
3const picker = new TimepickerUI('#timepicker', {
4  clock: { showSeconds: true }
5});
6picker.create();
7
8// picker.on is typed against TimepickerEventMap -
9// the handler payload type is inferred from the event name
10picker.on('confirm', (data) => {
11  // data: ConfirmEventData
12  console.log(data.hour, data.minutes, data.seconds, data.type, data.autoCommit);
13});
14
15picker.on('select:second', (data) => {
16  // data: SelectSecondEventData
17  console.log(data.seconds);
18});
19
20picker.on('select:period', (data) => {
21  // data: SelectPeriodEventData
22  console.log(data.type); // 'AM' | 'PM'
23});
24
25picker.on('switch:face', (data) => {
26  // data: SwitchFaceEventData
27  console.log(data.face); // 'hours' | 'minutes' | 'seconds'
28});
29
30picker.on('update', (data) => {
31  // data: UpdateEventData
32  console.log(data.hour, data.minutes, data.seconds, data.type);
33});
34
35picker.on('error', (data) => {
36  // data: ErrorEventData
37  console.error(data.error, data.inputHour, data.inputMinute, data.inputSecond);
38});
39
40picker.once('open', (data) => {
41  // data: OpenEventData
42  console.log(data.hour, data.minutes, data.seconds);
43});

1import { TimepickerUI } from 'timepicker-ui';
2
3const picker = new TimepickerUI('#timepicker', { range: { enabled: true } });
4picker.create();
5
6picker.on('range:change', (data) => {
7  // data: RangeChangeEventData
8  console.log(data.part, data.from, data.to);
9});
10
11picker.on('switch:view', (data) => {
12  // data: SwitchViewEventData
13  console.log(data.view); // 'clock' | 'keyboard'
14});
15
16// A name outside TimepickerEventName still compiles; data is unknown
17picker.on('my:custom', (data) => console.log(data));

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}

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});

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}