jb-time-picker

jb-time-picker is a 24-hour SVG time picker web component. Users can drag or tap the wheel text to change hour, minute, and optional second values; see the default picker demo.

• Uses an object value: { hour, minute, second }.
• Supports hour, minute, and second selection. Demo
• Can hide the second unit for hour/minute-only picking. Demo
• Supports Persian digit display while keeping .value numeric. Demo
• Supports optional time units with muted visual style. Demo
• Exposes CSS variables and CSS parts for clock customization. Demo

When to use

Use jb-time-picker when users need a visual clock-like picker for time values. Demo

Use jb-time-input when the user should type a time in an input field instead of using the SVG wheel.

Demo

• Demo for the default picker.
• Demo for hour/minute-only mode.
• Demo for Persian digits.
• Demo for style recipes and CSS parts.
• CodePen for a standalone example.

React

The package includes a React wrapper. See react/README.md and the React usage demo.

Installation

npm i jb-time-picker

import 'jb-time-picker';

<jb-time-picker></jb-time-picker>

CDN

<script src="https://unpkg.com/jb-time-picker/dist/jb-time-picker.umd.js"></script>

API reference

Attributes

| name | type | default | description | | --- | --- | --- | --- | | value | string | none | Initial time value. Accepts HH:mm, HH:mm:ss, or JSON such as {"hour":3,"minute":10,"second":20. Demo | | second-enabled | boolean | true | Shows the second unit. Empty attribute and "true" mean true; "false" means false. Demo | | leading-zero | boolean | false | Displays values below 10 with a leading zero. Demo | | optional-units | string | "" | Comma or space separated list of muted units: hour, minute, second. Demo | | show-persian-number | boolean | locale based | Displays Persian digits while .value remains numeric. Demo | | text-width | number | null | SVG textLength used to align time text for custom fonts. Demo |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | { hour: number; minute: number; second?: number } | no | Current selected time. Values are clamped to valid ranges. Demo | | secondEnabled | boolean | no | Shows or hides the second unit. Demo | | leadingZero | boolean | no | Displays 02 instead of 2 for values below 10. Demo | | optionalUnits | Array<'hour' \| 'minute' \| 'second'> | no | Units shown as optional/muted. Demo | | showPersianNumber | boolean | no | Displays Persian digits in the SVG text. Demo | | textWidth | number \| null | no | SVG text width used for alignment. Demo | | focusedTimeUnit | 'hour' \| 'minute' \| 'second' \| null | no | Currently focused unit. Prefer setTimeUnitFocus() for updates. Demo |

Methods

| name | returns | description | | --- | --- | --- | | setTimeUnitFocus(timeUnit) | void | Focuses hour, minute, or second so its text and indicator use the active color. Demo |

Events

| event | description | | --- | --- | | load | Dispatched from connectedCallback before initialization. Demo | | init | Dispatched from connectedCallback after initialization. Demo | | change | Dispatched when the user changes a time unit. Programmatic .value updates do not dispatch change. Demo |

Value

Set and read the time through the .value property; see the controlled value demo and value interaction demo.

const timePicker = document.querySelector('jb-time-picker');

timePicker.value = { hour: 3, minute: 10, second: 20 };

console.log(timePicker.value); // { hour: 3, minute: 10, second: 20 }

In HTML, use a compact string or JSON:

<jb-time-picker value="03:10:20"></jb-time-picker>
<jb-time-picker value='{"hour":3,"minute":10,"second":20}'></jb-time-picker>

Focus a time unit

Use setTimeUnitFocus() when an interaction should guide the user to a specific unit. Demo

const timePicker = document.querySelector('jb-time-picker');

timePicker.setTimeUnitFocus('hour');
timePicker.setTimeUnitFocus('minute');
timePicker.setTimeUnitFocus('second');

Disable seconds

Use this when the picker should only collect hour and minute. Demo

<jb-time-picker second-enabled="false"></jb-time-picker>

document.querySelector('jb-time-picker').secondEnabled = false;

Display options

Use the display properties for leading zeros, optional units, localized digits, and custom text alignment: leading zero, optional unit, Persian digits, and text width.

const timePicker = document.querySelector('jb-time-picker');

timePicker.leadingZero = true;
timePicker.optionalUnits = ['second'];
timePicker.showPersianNumber = true;
timePicker.textWidth = 150;

<jb-time-picker
  leading-zero
  optional-units="second"
  show-persian-number
  text-width="150"
></jb-time-picker>

textWidth is useful when custom fonts make narrow digits such as 1 look visually misaligned with wider digits such as 8. A practical range is usually 150 to 300.

RTL layouts

Place the picker in an RTL container when it is part of a right-to-left interface. Demo

CSS parts and variables

For complete styling guidance, live examples, official parts, custom states, and copyable style recipes, see Styling and the style gallery.

jb-time-picker {
  --jb-time-picker-hour-color: #2563eb;
  --jb-time-picker-minute-color: #059669;
  --jb-time-picker-second-color: #dc2626;
}

jb-time-picker::part(outer-circle) {
  opacity: 0.9;
}

Accessibility notes

• The component is an SVG interaction surface, not a native form control. Review the interactive demo when adding an accessible surrounding label.
• It does not currently attach ElementInternals or submit a form value automatically.
• Add surrounding labels and summary text in your app when screen-reader users need an accessible time editing flow.

Related Docs

• See jb-time-picker/react for React usage and jb-time-input for typed time input.
• See All JB Design System Component List for more components.
• Use Contribution Guide if you want to contribute to this component.

AI agent notes

• Import jb-time-picker once before using <jb-time-picker>.
• Use .value as the canonical API; it is an object, not a string.
• Use value="HH:mm:ss" or a JSON string only for initial markup.
• Use secondEnabled = false or second-enabled="false" for hour/minute-only picking.
• Use setTimeUnitFocus('hour' | 'minute' | 'second') to change the focused unit.
• Listen to change for user edits. Programmatic .value updates are silent.
• This package includes custom-elements.json and points to it with the package.json customElements field. The field is documented by the Custom Elements Manifest project in Referencing manifests from npm packages.
• In custom-elements.json, exports.kind: "js" describes JavaScript/TypeScript exports and exports.kind: "custom-element-definition" maps the jb-time-picker tag name to JBTimePickerWebComponent.