jquery-timepicker

jquery-timepicker (published to npm as timepicker) is a jQuery plugin that turns any text input into a Google Calendar-style time picker. It renders a scrollable dropdown of time options positioned relative to the input, supports full keyboard navigation, and lets users type free-form time strings that get parsed, rounded, and validated automatically.

The plugin is configuration-heavy rather than component-heavy: nearly every behavior — step interval, selectable time range, display format, localization, disabled ranges, relative-duration labels — is controlled through a single settings object or equivalent HTML data attributes, with no build step or framework dependency beyond jQuery itself.

What You Get

• Drop-in jQuery plugin — attach with one call, $('.time-input').timepicker(options), no framework or build tooling required.
• Configurable dropdown of time slots — step interval, min/max time, and disabled time ranges are all declarative options.
• Free-text time parsing — users can type values like “5p” or “17:30” and have them normalized automatically.
• HTML data-attribute configuration — every option can also be set via data-* attributes on the input, overriding JS defaults per element.
• Rich event API — changeTime, selectTime, showTimepicker, hideTimepicker, timeFormatError, and timeRangeError events for hooking into picker state.
• CSS-only theming — dropdown markup uses plain ui-timepicker-* classes, styleable without touching the plugin’s JS.

Common Use Cases

• Booking and scheduling forms — restrict selectable times to business hours with minTime/maxTime and block out reserved slots with disableTimeRanges.
• Legacy jQuery admin panels — add a lightweight time picker to server-rendered forms without introducing a modern frontend framework.
• Duration-relative pickers — pair with showDuration and durationTime to show “starts in 2 hours”-style relative labels for appointment or event scheduling.
• Mobile-friendly time selection — switch to useSelect to render a native <select> instead of the dropdown, avoiding on-screen keyboard/touch quirks on small screens.

Under The Hood

Architecture The plugin splits cleanly between a framework-agnostic core and a jQuery-facing shim. src/timepicker/index.js defines a Timepicker class that operates directly on a native DOM element (not a jQuery wrapper), holding parsed settings and exposing methods for value formatting, row lookup, and event dispatch via native CustomEvents. Supporting modules — rounding.js for step-rounding math, render.js for building the dropdown’s list markup, defaults.js/constants.js for configuration — are each single-purpose and import cleanly into the core class. The published entry point, jquery.timepicker.js, is a UMD wrapper (built by Rollup) that registers $.fn.timepicker using the classic jQuery-plugin method-dispatch convention (a single entry function switching on a string method name), instantiating the underlying Timepicker class per element. This separation means the core logic could in principle be reused without jQuery, though the shipped build is jQuery-only; the UMD wrapper itself still leans on older var-based, non-class style, so the codebase reads as a partially modernized rewrite rather than a uniform one.

Tech Stack The runtime dependency is jQuery 3.x only. The build pipeline uses Rollup with @rollup/plugin-babel (via @babel/preset-env) to transpile the ES6 class-based source into the UMD bundle, rollup-plugin-terser for minification, and rollup-plugin-copy to stage the CSS/JS deliverables listed in package.json’s files field. Tests run under Jest with babel-jest handling the same Babel transform. Linting is configured via a minimal .eslintrc.json, and formatting goes through prettier-eslint. A hand-maintained .d.ts file ships alongside the JS source for TypeScript consumers, authored separately rather than generated from source.

Code Quality The project has a real Jest test suite (src/__tests__/) covering time-string parsing, rounding behavior, rendering, and integration scenarios, exercising the Timepicker class directly rather than through simulated DOM events only. Naming and style are inconsistent across the codebase’s two eras: the newer core modules use ES6 classes, arrow functions, and destructuring, while the UMD wrapper retains older var-based jQuery-plugin conventions and a module-level mutable _lang variable. No CI configuration (GitHub Actions or similar) was found in the repo, so it’s unclear whether the test suite runs automatically on contribution. Error handling favors dispatching descriptive DOM events (timeFormatError, timeRangeError) over throwing, which fits the plugin’s event-driven usage pattern.

API Design The primary ergonomic strength is flexible configuration: every option can be set through the JS settings object or as an equivalent data-* HTML attribute, so server-rendered markup can configure each picker instance independently without extra JS. The event model dispatches plain CustomEvents on the target element rather than a jQuery-specific pub/sub channel, so consumers can listen with either addEventListener or jQuery’s .on(). The option surface is broad — several dozen documented settings — which gives fine control but means newcomers need to read a long README table rather than infer behavior from a handful of props. Getting started requires only a single .timepicker() call, which keeps the common case simple even though the full API is large.