Material Design-style Time Picker Web Component – clock-timepicker

clock-timepicker is a time picker Web Component that provides an Android Material Design-inspired clock interface for selecting time or duration values.

It’s a refactored, dependency-free version of an older jQuery plugin: Android-style Analog Clock Time Picker Plugin With jQuery.

Features:

• Web Component Architecture: Uses standard Custom Elements API. Compatible with vanilla JavaScript, React, Angular, Vue, and other frameworks.
• Adaptive Interface: Automatically switches between compact desktop mode and larger mobile popup based on device capabilities.
• CSS Variables for Theming: Exposes over 30 CSS custom properties for granular control over colors, spacing, fonts, and shadows.
• Keyboard Navigation: Full keyboard support including arrow keys for navigation, direct number entry, and escape to cancel changes.
• Configurable Precision: Set custom step values to restrict selections to specific intervals like 5-minute or 15-minute increments.
• Duration Mode: Can function as a duration picker with negative values and optional plus sign display for positive durations.
• Shadow DOM Encapsulation: Keeps internal styles isolated from page CSS while leaving the input element accessible for framework bindings.

How to use it:

1. Install clock-timepicker from NPM if you’re using a build process.

# NPM
$ npm install clock-timepicker

Then, import it into your JavaScript file.

import 'clock-timepicker';

2. Or download the script and include it directly in your HTML.

<script type="module" src="./dist/clock-timepicker.js"></script>

3. Add the clock-timepicker component to your project. That’s it.

<clock-timepicker></clock-timepicker>

4. Customize the time picker with the following options.

You can set options either as HTML attributes (e.g., cancel-text="Abort") or as properties on the DOM element directly (element.cancelText = 'Abort').

• animationDuration: Sets the animation speed in milliseconds when switching between the hour, minute, and second views. Default: 300.
• autosize: When set to true, the input field will automatically resize to fit the displayed time. Default: false.
• cancelText: The text displayed on the “Cancel” button in the mobile view. Default: 'Cancel'.
• disabled: If true, the timepicker is non-interactive. Default: false.
• format: A string that defines the time format and which parts are shown (e.g., ‘HH:mm’, ‘h:mm:ss’, ‘mm:ss’). Default: 'HH:mm'.
• maximum: The latest time or duration that can be selected by the user. Default: '23:59:59'.
• minimum: The earliest time or duration that can be selected. Default: '00:00:00'.
• okText: The text displayed on the “OK” button in the mobile view. Default: 'OK'.
• precision: Defines the granularity of the time picker, essentially setting the step for minutes or seconds. Default: '00:00:01'.
• required: If true, the input field must always have a value and cannot be cleared. Default: false.
• separator: The character used to separate the hours, minutes, and seconds. Default: ':'.
• usePlusSign: If true, a plus sign (+) is shown for positive durations, which is useful when negative values are also allowed. Default: false.
• value: The initial time displayed in the input. If required is true and no value is set, it defaults to ’00:00:00′. Default: undefined.
• vibrate: If true, the component provides haptic feedback (if the device supports it) during interaction. Default: true.

<clock-timepicker required usePlusSign format="H:mm" value="4:00" minimum="-10:00" maximum="10:00"></clock-timepicker>

5. You can listen for standard DOM events to track user interaction.

Event	Timing	Description
blur	When focus leaves the input	Fires after user clicks outside or tabs away from the picker.
change	When popup closes with modified value	Triggers only if the time value changed during the interaction session.
focus	When input receives focus	Fires when user clicks into the input or tabs to it.
input	During popup interaction	Emits continuously as user adjusts time while popup remains open.

const picker = document.querySelector('clock-timepicker');
picker.addEventListener('change', (event) => {
  console.log('Time changed to:', event.target.value);
});

6. Customize appearance by setting CSS custom properties:

Primary Color Variables:

Variable	Default	Description
–clock-timepicker-accent-color	#0797ff	Primary theme color, used as fallback for multiple elements.
–clock-timepicker-header-background	inherit	Mobile header background. Falls back to accent color.
–clock-timepicker-face-selection-color	inherit	Selected number highlight color. Falls back to accent color.
–clock-timepicker-button-color	inherit	Button text color. Falls back to accent color.

Layout Variables:

Variable	Default	Description
–clock-timepicker-popup-size	200px	Width and height of desktop popup.
–clock-timepicker-popup-border-radius	5px	Corner rounding of popup container.
–clock-timepicker-popup-shadow	rgba(0,0,0,0.14) 0px 4px 20px 0px	Drop shadow for popup elevation.
–clock-timepicker-button-gap	30px	Spacing between action buttons.

Typography Variables:

Variable	Default	Description
–clock-timepicker-font-family	Arial	Font family for all text in the picker.
–clock-timepicker-header-font-size	40px	Size of time display in mobile header.
–clock-timepicker-button-font-size	20px	Size of action button text.

Clock Face Variables:

Variable	Default	Description
–clock-timepicker-face-color	#eeeeee	Background circles behind numbers.
–clock-timepicker-face-hover-color	#dddddd	Circle color on number hover.
–clock-timepicker-outer-numbers-color	#000000	Text color for outer ring numbers.
–clock-timepicker-inner-numbers-color	#888888	Text color for inner ring numbers (24-hour mode).

Button Customization:

Variable	Default	Description
–clock-timepicker-button-background	none	Fill color behind buttons.
–clock-timepicker-button-border	none	Border around buttons.
–clock-timepicker-button-padding	none	Internal spacing within buttons.
–clock-timepicker-button-outline	none	Focus outline styling.
–clock-timepicker-button-shadow	none	Drop shadow for buttons.
–clock-timepicker-button-ok-color	inherit	Specific override for OK button text.
–clock-timepicker-button-cancel-color	inherit	Specific override for cancel button text.

Keyboard Interactions:

Key	Action
Enter	Confirms current selection and closes popup.
Escape	Cancels changes and restores previous value.
ArrowLeft	Moves focus to previous time part (hours → minutes → seconds).
ArrowRight	Moves focus to next time part.
ArrowUp	Increments currently focused time part by precision value.
ArrowDown	Decrements currently focused time part by precision value.
Backspace/Delete	Sets focused time part to zero. Clears entire value if already 00:00 and not required.
0-9	Direct digit entry. Automatically advances to next part or closes when max value reached.
Separator (: by default)	Advances to next time part or closes popup at last part.
+ / –	Sets sign for duration values when minimum or maximum allows negative values.

Alternatives

• Flatpickr: A feature-rich date and time picker with plugin support and wider adoption, but includes date selection features you may not need and requires more configuration for time-only scenarios.
• Tempus Dominus: Bootstrap-focused datetime picker that integrates tightly with Bootstrap styling conventions but adds a significant dependency on Bootstrap’s JavaScript and CSS if you’re not already using that framework.

FAQs

Q: How do I restrict time selection to business hours only?
A: Set the minimum and maximum attributes to your desired range. For 9 AM to 5 PM, use minimum="09:00" and maximum="17:00". The clock face will gray out unavailable times, and keyboard input will clamp to the valid range.

Q: Can I use this for elapsed time where users might enter values over 24 hours?
A: Yes, but you need to configure it properly. Set format="HH:mm" or format="HH:mm:ss" and adjust the maximum value to something like maximum="99:59:59". The component supports any numeric time values, not just valid clock times.

Q: How do I programmatically set the time value from JavaScript?
A: Access the element and set its value property directly: document.querySelector('clock-timepicker').value = '14:30'. The component will validate the input against your format, minimum, and maximum settings. If you need to set the value before the component initializes, use the value attribute in your HTML instead, as property assignment on unregistered custom elements won’t work.

Q: The picker is too small on desktop. How do I make it bigger?
A: Set the --clock-timepicker-popup-size CSS variable to a larger value. For example: clock-timepicker { --clock-timepicker-popup-size: 300px; }. This controls both width and height of the popup container. You may also want to increase font sizes using --clock-timepicker-header-font-size and --clock-timepicker-button-font-size to maintain proportions.

The post Material Design-style Time Picker Web Component – clock-timepicker appeared first on CSS Script.