Troubleshooting

The picker opens but has no styles

Fix:

1. Import timepicker-ui/main.css once, for example in your app's entry file. It contains the core styles and the default basic theme.
2. For another theme, also import timepicker-ui/theme-<name>.css and set ui.theme to the same name.
   index.tsCopy

   1import { TimepickerUI } from 'timepicker-ui';
   2import 'timepicker-ui/main.css';
   3import 'timepicker-ui/theme-dark.css';
   4
   5const picker = new TimepickerUI('#time', { ui: { theme: 'dark' } });
   6picker.create();

Why: The package ships its CSS as separate files, so you load only the themes you use. timepicker-ui/index.css contains the core styles and all 12 themes in one file.

Nothing happens when the input is clicked

Fix:

1. Call create() after new TimepickerUI(...). The handlers that open the picker on click and on Enter are added by create(), not by the constructor.
   index.tsCopy

   1import { TimepickerUI } from 'timepicker-ui';
   2
   3const picker = new TimepickerUI('#time');
   4picker.create();

2. If the console shows Input element not found, the selector matched nothing when the code ran, or the element has no <input> inside it. Run the code after the element is in the page.

A range, timezone or wheel option is ignored, or an error event fires

Fix:

1. Import the plugin from timepicker-ui/plugins/<name> and pass it to PluginRegistry.register() once, before the first new TimepickerUI(...).
   index.tsCopy

   1import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
   2import { RangePlugin } from 'timepicker-ui/plugins/range';
   3
   4PluginRegistry.register(RangePlugin);
   5
   6const picker = new TimepickerUI('#time', { range: { enabled: true } });
   7picker.create();

2. A missing plugin is reported only through the error event, when the picker opens. Listen to it to see the message.
   index.tsCopy

   picker.on('error', ({ error }) => console.warn(error));

Why: Each picker sets up its plugins in its constructor, so a plugin registered after new TimepickerUI(...) does not work in that picker. Without its plugin, the picker leaves out the range and timezone controls and shows the clock instead of the wheel. With range.enabled set, OK then does not close the picker.

ui.theme: 'my-theme' has no effect

Fix:

1. Pass your class name in ui.cssClass instead. The picker adds the class to .tp-ui-wrapper when it opens.
   index.tsCopy

   1const picker = new TimepickerUI('#time', {
   2  ui: { cssClass: 'my-theme' },
   3});
   4picker.create();

2. Set the --tp-* variables under .tp-ui-wrapper.my-theme. CSS Variables lists them.
   index.cssCopy

   1.tp-ui-wrapper.my-theme {
   2  --tp-bg: #ffffff;
   3  --tp-text: #1d1b20;
   4  --tp-primary: #0b57d0;
   5  --tp-on-primary: #ffffff;
   6}

Why: ui.theme selects one of the 12 built-in themes. The picker writes the name to the data-theme attribute of the modal and does not add it as a class, so a rule such as .my-theme never matches.

TypeScript rejects a custom ui.theme name

Fix: Leave ui.theme unset or use a built-in name, and pass your own class in ui.cssClass. The ui.theme entry above shows the CSS.

Why: ui.theme is typed as a union of the 12 built-in theme names.

The modal shows behind a header or inside a clipped container

Fix:

1. If you set ui.appendTo, point it at an element outside the clipped container, or remove the option so the modal goes to <body>.
2. The modal has z-index: 5000. If your header has a higher z-index, lower the header's value, or raise the modal's in CSS that loads after timepicker-ui/main.css.
   index.cssCopy

   1.tp-ui-modal {
   2  z-index: 10000;
   3}

Why: The modal is position: fixed. Inside an ancestor with transform or filter, a fixed element is placed relative to that ancestor instead of the viewport, and its z-index only counts inside it. --tp-z-modal is defined in :root, but no rule reads it, so changing it does nothing.

My CSS does not override the built-in styles

Fix:

1. Give the picker a class with ui.cssClass, for example 'my-picker'.
2. Start each selector with .tp-ui-wrapper.my-picker. Built-in state rules such as .tp-ui-hour.active and .tp-ui-hour.mobile.active use two or three classes, and the prefix adds two more.
   index.cssCopy

   1.tp-ui-wrapper.my-picker .tp-ui-hour.active,
   2.tp-ui-wrapper.my-picker .tp-ui-minutes.active {
   3  background-color: #111111;
   4  color: #ffffff;
   5}

3. See Specificity on the CSS Classes page.

Why: A rule loses when it has fewer classes than the built-in one, or the same number and loads earlier.

ReferenceError: document is not defined or TimepickerUI requires browser environment in Next.js, Nuxt or SvelteKit

Fix:

1. Create the picker in a hook that runs only in the browser: useEffect in React, onMounted in Vue and Nuxt, onMount in Svelte and SvelteKit. In the Next.js App Router, the file also needs 'use client'.
   index.tsxCopy

   1'use client';
   2
   3import { useEffect, useRef } from 'react';
   4import { TimepickerUI } from 'timepicker-ui';
   5
   6export function TimeField() {
   7  const inputRef = useRef<HTMLInputElement>(null);
   8
   9  useEffect(() => {
   10    if (!inputRef.current) return;
   11    const picker = new TimepickerUI(inputRef.current);
   12    picker.create();
   13    return () => picker.destroy();
   14  }, []);
   15
   16  return <div className="tp-ui"><input ref={inputRef} type="text" /></div>;
   17}

2. Read document and window only inside that hook as well.
3. Server Rendering shows the setup for Next.js, Nuxt and SvelteKit.

Why: Importing timepicker-ui on the server is safe, because no module reads window or document when it loads. The constructor needs a browser: it throws TimepickerUI requires browser environment when window is undefined. ReferenceError: document is not defined comes from your own code, for example a document.querySelector() call in the component body.

Two pickers open, or events fire twice, in React development mode

Fix: Return () => picker.destroy() from the effect that creates the picker.

1useEffect(() => {
2  if (!inputRef.current) return;
3  const picker = new TimepickerUI(inputRef.current);
4  picker.create();
5  return () => picker.destroy();
6}, []);

Why: In development, Strict Mode runs each effect, then its cleanup, then the effect again. Without a cleanup, the first picker stays on the input next to the second one, and both open on click. destroy() removes the picker's listeners and its modal.

Failed to execute 'removeChild' on 'Node' when a React component unmounts

Fix: Wrap the input in an element with the tp-ui class. The picker then uses that element as its root and leaves the input where React rendered it.

1return (
2  <div className="tp-ui">
3    <input ref={inputRef} type="text" />
4  </div>
5);

Why: Given a bare <input>, the constructor moves it into a new div.tp-ui, and destroy() does not remove that div. React still expects the input in its original parent, so removing it can fail. timepicker-ui-react renders the wrapper for you.

The input value does not update React state

Fix:

1. Set state in callbacks.onConfirm. It runs when the user confirms a time, after the picker has written it to the input.
   index.tsxCopy

   1const [time, setTime] = useState('');
   2
   3useEffect(() => {
   4  const input = inputRef.current;
   5  if (!input) return;
   6  const picker = new TimepickerUI(input, {
   7    callbacks: { onConfirm: () => setTime(input.value) },
   8  });
   9  picker.create();
   10  return () => picker.destroy();
   11}, []);

2. With timepicker-ui-react, pass value and update it in onConfirm.
   index.tsxCopy

   1import { useState } from 'react';
   2import { Timepicker } from 'timepicker-ui-react';
   3
   4export function TimeField() {
   5  const [time, setTime] = useState('10:00 AM');
   6
   7  return (
   8    <Timepicker
   9      value={time}
   10      onConfirm={({ hour, minutes, type }) => setTime(`${hour}:${minutes} ${type}`)}
   11    />
   12  );
   13}

Why: The picker sets input.value directly and does not dispatch input or change events, so React's onChange never runs.

Listeners or a modal stay after a route change

Fix: Call picker.destroy() in your framework's cleanup hook: the function returned from useEffect in React, onBeforeUnmount in Vue, ngOnDestroy in Angular, or the function returned from onMount in Svelte.

1<script setup lang="ts">
2import { onBeforeUnmount, onMounted, ref } from 'vue';
3import { TimepickerUI } from 'timepicker-ui';
4
5const input = ref<HTMLInputElement | null>(null);
6let picker: TimepickerUI | undefined;
7
8onMounted(() => {
9  picker = new TimepickerUI(input.value!);
10  picker.create();
11});
12
13onBeforeUnmount(() => picker?.destroy());
14</script>
15
16<template>
17  <div class="tp-ui"><input ref="input" type="text" /></div>
18</template>

Why: An open modal sits in <body>, or in the ui.appendTo element, outside your component. If the route changes while the picker is open, the modal stays, and by default the page scroll stays locked. destroy() removes the modal, the picker's listeners and the scroll lock.

ui.mode: 'wheel' or 'compact-wheel' still shows a clock

Fix: Import WheelPlugin from timepicker-ui/plugins/wheel and register it once, before creating the picker.

1import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
2import { WheelPlugin } from 'timepicker-ui/plugins/wheel';
3
4PluginRegistry.register(WheelPlugin);
5
6const picker = new TimepickerUI('#time', { ui: { mode: 'wheel' } });
7picker.create();

Why: Without the plugin, the picker falls back to the clock face and emits error with the message WheelPlugin is not registered. Import and register it: PluginRegistry.register(WheelPlugin).