Skip to content
Back to search

timepicker-ui

timepicker-ui is an easy library with timepicker. Fully wrote with TypeScript. This library is based on Material Design from Google.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pglejzer/timepicker-ui with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pglejzer/timepicker-ui'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pglejzer--timepicker-ui/badge.svg)](/listings/pglejzer--timepicker-ui)

HTML

<a href="/listings/pglejzer--timepicker-ui"><img src="/api/listings/pglejzer--timepicker-ui/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install timepicker-ui

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 288 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # timepicker-ui
  2. A time picker for web forms. Attach it to an `<input>` and users pick a time on a clock face or a scroll wheel.
  3. [![npm version](https://badge.fury.io/js/timepicker-ui.svg)](https://badge.fury.io/js/timepicker-ui)
  4. [![downloads](https://img.shields.io/npm/dm/timepicker-ui)](https://npmcharts.com/compare/timepicker-ui?minimal=true)
  5. [![license](https://img.shields.io/badge/license-MIT-green.svg)](https://img.shields.io/npm/l/timepicker-ui)
  6. [![Coverage Status](https://coveralls.io/repos/github/pglejzer/timepicker-ui/badge.svg?branch=main)](https://coveralls.io/github/pglejzer/timepicker-ui?branch=main)
  7. [![Tests](https://github.com/pglejzer/timepicker-ui/actions/workflows/tests.yml/badge.svg)](https://github.com/pglejzer/timepicker-ui/actions/workflows/tests.yml)
  8. [![Socket Badge](https://badge.socket.dev/npm/package/timepicker-ui/4.7.0)](https://badge.socket.dev/npm/package/timepicker-ui/4.7.0)
  9. [Live demo](https://timepicker-ui.vercel.app/) · [Documentation](https://timepicker-ui.vercel.app/docs) · [Changelog](./CHANGELOG.md) · [React wrapper](https://github.com/pglejzer/timepicker-ui-react)
  10. ## Why timepicker-ui
  11. - Zero dependencies.
  12. - ~29 KB gzipped core. The range plugin is about 7 KB, the timezone plugin about 3 KB, the wheel plugin about 10 KB, and a plugin only gets bundled if you import it ([bundle stats](https://timepicker-ui.vercel.app/bundle-stats)).
  13. - [Clock](https://timepicker-ui.vercel.app/examples/basic/getting-started), [wheel](https://timepicker-ui.vercel.app/examples/plugins/wheel) or compact wheel (a small dropdown under the input).
  14. - Plain JS API, so it works the same in React, Vue, Angular, Svelte or without a framework.
  15. - Doesn't touch `window` or `document` on import, so it's safe in Next.js, Nuxt and other SSR setups.
  16. - Keyboard and screen reader support. All texts, the screen-reader ones included, can be translated via `labels`.
  17. ## Features
  18. - 12h / 24h, hour and minute steps, [disabled times](https://timepicker-ui.vercel.app/docs/features/disabled-time)
  19. - Optional [seconds](https://timepicker-ui.vercel.app/docs/features/seconds) (`HH:MM:SS`) in the clock, wheel and compact wheel
  20. - [12 themes](https://timepicker-ui.vercel.app/docs/features/themes) (Material 2/3, Crane, Dark, Cyberpunk, Blueprint, ...)
  21. - [Inline mode](https://timepicker-ui.vercel.app/docs/features/inline-mode) (with an embedded variant for your own dialog), [clear button](https://timepicker-ui.vercel.app/docs/features/clear-button), [mobile layout](https://timepicker-ui.vercel.app/docs/features/mobile)
  22. - [Time ranges](https://timepicker-ui.vercel.app/examples/plugins/range) (linked or independent From/To, in the clock, wheel and compact wheel) and [timezones](https://timepicker-ui.vercel.app/examples/plugins/timezone) via plugins
  23. - Disable times with a function (`clock.isTimeDisabled`)
  24. - [TypeScript](https://timepicker-ui.vercel.app/docs/api/typescript) types included
  25. ## Installation
  26. ```bash
  27. npm install timepicker-ui
  28. ```
  29. ## Quick start
  30. ```html
  31. <input id="timepicker" type="text" />
  32. ```
  33. ```javascript
  34. import { TimepickerUI } from "timepicker-ui";
  35. import "timepicker-ui/main.css";
  36. const input = document.querySelector("#timepicker");
  37. const picker = new TimepickerUI(input, {
  38. clock: { type: "24h" },
  39. ui: { theme: "dark" },
  40. callbacks: {
  41. onConfirm: (data) => console.log("Selected:", data),
  42. },
  43. });
  44. picker.create();
  45. ```
  46. No global CSS reset is needed: the picker sets `box-sizing: border-box` on its own elements ([details](https://timepicker-ui.vercel.app/docs/installation)).
  47. ## API
  48. ```javascript
  49. picker.create(); // render the picker and attach it to the input
  50. picker.open();
  51. picker.close();
  52. picker.destroy();
  53. picker.getValue(); // { hour, minutes, seconds, type, time }, seconds only with clock.showSeconds
  54. picker.setValue("14:30"); // "2:30 PM" works too
  55. picker.setValue("14:30:15"); // with clock.showSeconds
  56. picker.setOptions({ ui: { theme: "crane" } });
  57. picker.setRange({ from: "09:00", to: "17:00" }); // needs RangePlugin
  58. picker.getRange();
  59. picker.setActivePart("to");
  60. picker.getActivePart(); // "from", "to" or null
  61. picker.setRangeCaptions({ from: "Mon", to: "Tue" }); // needs RangePlugin
  62. picker.setView("keyboard"); // or "clock"
  63. picker.getView();
  64. picker.clear();
  65. picker.refreshDisabledTime(); // after the data behind clock.isTimeDisabled changes
  66. const off = picker.on("confirm", (data) => {}); // on() and once() return a function that removes the handler
  67. off();
  68. picker.on("confirm", (data) => {});
  69. picker.on("cancel", (data) => {});
  70. picker.on("open", () => {});
  71. picker.on("update", (data) => {});
  72. picker.on("clear", (data) => {});
  73. picker.on("error", (data) => {});
  74. picker.once("confirm", handler);
  75. picker.off("confirm", handler);
  76. TimepickerUI.getById("my-id");
  77. TimepickerUI.getAllInstances();
  78. TimepickerUI.isAvailable("#timepicker");
  79. TimepickerUI.destroyAll();
  80. import { parseTime, formatTime, createDisabledTimeCheck } from "timepicker-ui"; // no picker needed
  81. ```
  82. Docs: [methods](https://timepicker-ui.vercel.app/docs/api/methods), [events](https://timepicker-ui.vercel.app/docs/api/events)
  83. ## Options
  84. Grouped by area. Pass only what you need, the rest has defaults ([full list](https://timepicker-ui.vercel.app/docs/api/options)).
  85. ```typescript
  86. new TimepickerUI(input, {
  87. clock: {
  88. type: "12h" | "24h" | "auto", // default "12h"; "auto" follows the browser locale
  89. incrementHours: 1,
  90. incrementMinutes: 1,
  91. showSeconds: false, // true adds seconds (HH:MM:SS)
  92. incrementSeconds: 1,
  93. disabledTime: { hours: [], minutes: [], seconds: [], ranges: "" },
  94. isTimeDisabled: ({ hour, minutes, seconds }) => false, // hour is 0-23
  95. defaultTime: "now" | { time, updateInput },
  96. },
  97. ui: {
  98. theme: "basic" | "dark" | "m3-green" | "crane" | "blueprint" | ...,
  99. mode: "clock" | "wheel" | "compact-wheel", // default "clock"
  100. animation: true,
  101. backdrop: true,
  102. initialView: "clock", // or "keyboard"
  103. editable: false,
  104. inline: { enabled: false, container: "#picker" | element, showButtons: false, autoUpdate: false, embedded: false, showTitle: true },
  105. clearButton: false, // or { clearInput: false } to keep the input value on Clear
  106. cssClass: "",
  107. },
  108. labels: { am, pm, ok, cancel, clear, clockTitle, hour, minute, second, valueText, rangeFrom, rangeTo, timezone, ... },
  109. behavior: { focusTrap: true, returnFocus: false, delayHandler: 0, id: "" },
  110. callbacks: { onConfirm, onCancel, onOpen, onUpdate, onSelectHour, onSelectMinute, onSelectSecond, onSelectPeriod, onClear, onError, ... },
  111. wheel: { placement: "auto" | "top" | "bottom", hideFooter: false, commitOnScroll: false, hideDisabled: false, ignoreOutsideClick: false },
  112. range: { enabled: false, linked: true, minDuration, maxDuration },
  113. timezone: { enabled: false, default, list },
  114. });
  115. ```
  116. ## Themes
  117. [Preview all of them](https://timepicker-ui.vercel.app/examples/themes/basic): `basic`, `crane`, `crane-straight`, `m3-green`, `m2`, `dark`, `glassmorphic`, `pastel`, `ai`, `cyberpunk`, `blueprint`, `blueprint-dark`.
  118. `main.css` is required and already includes `basic`. The rest are separate files:
  119. ```javascript
  120. import "timepicker-ui/main.css";
  121. import "timepicker-ui/theme-dark.css";
  122. new TimepickerUI(input, { ui: { theme: "dark" } });
  123. ```
  124. Or import `timepicker-ui/index.css` to get all of them. Writing your own theme: [styling guide](https://timepicker-ui.vercel.app/docs/advanced/styling).
  125. ## Plugins
  126. Range, timezone and wheel ship as separate imports. Register them once before creating pickers. You need `WheelPlugin` for the `wheel` and `compact-wheel` modes.
  127. ```javascript
  128. import { TimepickerUI, PluginRegistry } from "timepicker-ui";
  129. import { RangePlugin } from "timepicker-ui/plugins/range";
  130. import { TimezonePlugin } from "timepicker-ui/plugins/timezone";
  131. import { WheelPlugin } from "timepicker-ui/plugins/wheel";
  132. PluginRegistry.register(RangePlugin);
  133. PluginRegistry.register(TimezonePlugin);
  134. PluginRegistry.register(WheelPlugin);
  135. new TimepickerUI(input, { range: { enabled: true } });
  136. ```
  137. Registration is global. Call `PluginRegistry.register()` once, before you create pickers. Every picker created afterwards gets a small manager for each registered plugin.
  138. - A plugin does nothing unless the picker turns it on: `range.enabled`, `timezone.enabled`, or `ui.mode` set to `'wheel'` or `'compact-wheel'`.
  139. - A plugin registered after a picker was created is not available to that picker. Create the picker again.
  140. - Turning a feature on without its plugin registered emits `error`.
  141. Without a bundler, load the core UMD build and the plugin UMD builds you need. The core build exposes `TimepickerUI.PluginRegistry`.
  142. ```html
  143. <script src="https://cdn.jsdelivr.net/npm/timepicker-ui@4.7.0/dist/index.umd.js"></script>
  144. <script src="https://cdn.jsdelivr.net/npm/timepicker-ui@4.7.0/dist/plugins/range.umd.js"></script>
  145. <script>
  146. TimepickerUI.PluginRegistry.register(TimepickerUIRange.RangePlugin);
  147. new TimepickerUI('#timepicker', { range: { enabled: true } }).create();
  148. </script>
  149. ```
  150. The plugin globals are `TimepickerUIRange.RangePlugin`, `TimepickerUITimezone.TimezonePlugin` and `TimepickerUIWheel.WheelPlugin`.
  151. ## Upgrading
  152. From 4.6, 4.7 adds the range plugin in `wheel` and `compact-wheel`, `setView()` / `getView()`, `clear()`, `getActivePart()`, `setRangeCaptions()` and the `range:change` event. Some defaults changed: AM/PM is a radiogroup, the timezone combobox moved to `.tp-ui-timezone-selected`, `aria-valuetext` reads "7 of 12", and `dark` follows Material Design 3 tokens. The [CHANGELOG](./CHANGELOG.md) lists them under "Check before upgrading".
  153. From 4.5 to 4.6 nothing breaks. 4.6 adds `ui.inline.embedded`, `range.linked`, `clock.isTimeDisabled` with `refreshDisabledTime()`, the `setRange()` / `getRange()` / `setActivePart()` methods, and a remover returned by `on()` / `once()`. See the [CHANGELOG](./CHANGELOG.md).
  154. From 4.4, 4.5 adds optional seconds (`clock.showSeconds`) and fixes many bugs. It also renames many options to clearer names, for example `ui.initialView` instead of `ui.mobile`, and adds `setOptions()` in place of `update()`. The old names keep working until 5.0, and the [options page](https://timepicker-ui.vercel.app/docs/api/options) lists every pair. A few changes can affect an existing setup: the AM/PM part of the value is always `AM` / `PM` whatever `labels.am` / `labels.pm` say, out-of-range `clock.disabledTime.ranges` edges such as `25:00` are reported as errors, the old `.tp-ui-ripple` classes are gone, and some focus-ring and radius tokens changed. The [CHANGELOG](./CHANGELOG.md) lists them under "Check before upgrading".
  155. From 4.3 nothing breaks. 4.4 adds the `blueprint` and `blueprint-dark` themes, 16 new `labels.*` for screen-reader text, and Home/End/PageUp/PageDown keys. See the [CHANGELOG](./CHANGELOG.md).
  156. From 3.x, options are now grouped (`clock`, `ui`, `labels`, ...), events go through `picker.on()`, and CSS class names changed. There's a [migration guide](https://timepicker-ui.vercel.app/docs/migration-guide).
  157. From 2.x, you have to import the CSS yourself and some event names changed ([legacy guide](https://timepicker-ui.vercel.app/docs/legacy-migration)).
  158. ## Frameworks
  159. React:
  160. ```tsx
  161. import { useEffect, useRef } from "react";
  162. import { TimepickerUI } from "timepicker-ui";
  163. import "timepicker-ui/main.css";
  164. function TimePicker() {
  165. const ref = useRef<HTMLInputElement>(null);
  166. useEffect(() => {
  167. if (!ref.current) return;
  168. const picker = new TimepickerUI(ref.current);
  169. picker.create();
  170. return () => picker.destroy();
  171. }, []);
  172. return <input ref={ref} />;
  173. }
  174. ```
  175. There's also a [React wrapper](https://github.com/pglejzer/timepicker-ui-react) ([docs](https://timepicker-ui.vercel.app/react)). Vue and Angular examples are in the [quick start docs](https://timepicker-ui.vercel.app/docs/quick-start).
  176. ## Need a date picker?
  177. [datepicker-ui](https://timepicker-ui.vercel.app/datepicker) is the companion calendar from the same author. It has no dependencies, follows Material Design 3, is safe to import during server rendering and uses the same theme names, so the two pickers match. It covers single dates, ranges and multiple dates.
  178. ```bash
  179. npm install @pglejzer/datepicker-ui
  180. ```
  181. The [date and time guide](https://timepicker-ui.vercel.app/datepicker/docs/with-timepicker) shows how to use both pickers in one form.
  182. ## Coming in 5.0
  183. 5.0.0 is planned but has no release date yet. 4.5.0 prepares for it. Planned changes:
  184. - Plugins will be built and registered differently. `PluginRegistry.register(...)` and the exported plugin types (`PluginRegistry`, `Plugin`, `PluginManager`, `PluginFactory`, `TemplateProvider`, `ClearHandler`, `CoreState`, `EventEmitter`) will change. The built-in range, timezone and wheel plugins stay. A migration guide ships with 5.0.
  185. - CSS class names keep the `tp-ui-` prefix, but the part after it is reworked to follow Material Design component naming. Custom CSS that targets these classes will need updating. 5.0 ships a table of old and new names.
  186. - The options renamed in 4.5.0 lose their old names, for example `ui.mobile` (now `ui.initialView`) and `clock.smoothHourSnap` (now `clock.discreteHourJump`). The [options page](https://timepicker-ui.vercel.app/docs/api/options) lists every pair. The `select:am` / `select:pm` events go too (use `select:period`), and so does `update()` (use `setOptions()`).
  187. - `behavior.returnFocus` becomes `true` by default: on close, focus goes back to the input, or to the `data-open` element that opened the picker. Set `behavior.returnFocus: true` now to return focus to the input.
  188. - Code that is no longer needed is removed, including backward-compatibility paths for the deprecated items and dead code. This reduces bundle size and load cost for the core and each plugin. No size target is set yet. 4.5.0 already removes internal dead code that has no effect on the public API or markup. 5.0 removes the rest together with the items below.
  189. - Items deprecated in 4.5.0 are removed:
  190. - `OptionTypes` (use `TimepickerOptions`)
  191. - `clock.currentTime.locales`
  192. - `getValue().degreesHours` and `getValue().degreesMinutes`
  193. - `labels.toggleLabel`, `labels.format24Label`, `labels.timezoneSelectorLabel`
  194. - the legacy `focusInputAfterCloseModal` option (use `behavior.returnFocus`)
  195. - the `hide` event and `HideEventData` (never emitted)
  196. - the `range:get-disabled-time` and `range:update-disabled` events (never emitted)
  197. - `ErrorEventData.rejectedHour` and `rejectedMinute` (always `undefined`)
  198. - Also removed, because they do nothing or mislead:
  199. - internal events in the public `TimepickerEventMap` (`range:minute:commit`, `animation:*`) and its catch-all index signature, so `on('typo')` becomes a type error
  200. - `behavior.delayHandler` (it only delays closing and never debounced buttons)
  201. - `TimepickerUI.isAvailable()` (same as `document.querySelector(...) !== null`)
  202. - the undocumented DOM getters `hour`, `minutes`, `okButton`, `cancelButton`, `clockHand`
  203. - the callback arguments of `open(cb)` and `destroy()` in both forms, `destroy(cb)` and `destroy({ callback })` (use `once('open')` or run the code after the call)
  204. - `RangeManager`, `TimezoneManager` and `WheelManager` exported from the plugin entry points (you can't get an instance today, and the new plugin API replaces them)
  205. - Changed events and options:
  206. - `select:hour`, `select:minute` and `select:second` fire once when a value of their unit is picked, in every mode. Today, in clock mode, they fire when a field is activated, so picking an hour fires `select:minute`. To follow face changes, use `switch:face`, which 4.5.0 already emits
  207. - `ui.footer` replaces `ui.inline.showButtons` and `wheel.hideFooter`: `false` hides OK, Cancel and Clear in every mode, and `true` shows them in inline mode too
  208. - `behavior.commitOnChange` replaces `ui.inline.autoUpdate` and `wheel.commitOnScroll`: each picked value is written to the input and emits `confirm`, and the picker stays open
  209. - `wheel.ignoreOutsideClick` moves to `behavior.ignoreOutsideClick` and works in every mode, the clock modal included
  210. - the minute announcement reads `labels.minute`; `labels.announceMinute` is removed (its default is already `Minute` since 4.7.0)
  211. - `ui.cssClass` is applied to one element instead of two
  212. - Package and CSS:
  213. - about 50 CSS custom properties that no rule reads are removed, for example `--tp-tertiary-container`, `--tp-on-tertiary-container`, `--tp-radius`, `--tp-hover-bg` and 18 of the 34 `--tp-size-*` tokens. 5.0 lists them all
  214. - the `./plugins/*` wildcard in `package.json` `exports` is removed, while `./plugins/range`, `./plugins/timezone` and `./plugins/wheel` stay
  215. - `crane-straight` becomes a variant of `crane` with square corners (option name not decided)
  216. - `ui.keyboardIcon` / `ui.clockIcon` take an element or a factory function instead of an HTML string
  217. Details are on the [roadmap](https://timepicker-ui.vercel.app/docs/roadmap).
  218. ## Development
  219. See [`app/README.md`](./app/README.md).
  220. ## Contributing
  221. Issues and PRs welcome on [GitHub](https://github.com/pglejzer/timepicker-ui/issues).
  222. ## License
  223. MIT © [Piotr Glejzer](https://github.com/pglejzer)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.