jb-time-input

jb-time-input is a form-associated time input web component with a typed input surface and a touch-friendly jb-time-picker popover.

• Accepts and submits 24-hour time strings.
• Supports HH:mm:ss and hour/minute-only HH:mm mode.
• Opens a visual time picker on focus.
• Supports ArrowUp and ArrowDown to increase or decrease the focused time unit.
• Accepts Persian digits and stores English digits.
• Supports custom validation through jb-validation.
• Uses jb-input, jb-popover, jb-time-picker, and jb-button internally.
• Framework friendly: use it in pure JavaScript or in frameworks such as React, Vue, and Angular.

When to use

Use jb-time-input when users should type or edit a time value and may also benefit from a visual time picker. See the basic time input demo for the default interaction.

Use jb-time-picker when you need only the visual wheel picker without an input field.

Demo

• Explore the time input examples, including hour/minute-only mode, Persian digits, display options, and validation.
• Try the standalone CodePen example.

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm i jb-time-input

import 'jb-time-input';

<jb-time-input label="Time"></jb-time-input>

API reference

jb-time-input uses jb-input, jb-popover, jb-time-picker, and jb-button internally. For the full inner input styling and behavior model, see the jb-input API.

Attributes

| name | type | default | description | | --- | --- | --- | --- | | value | string | 00:00:00 | Time value. Use HH:mm:ss when seconds are enabled and HH:mm when second-enabled="false"; see the value demo. | | label | string | "" | Label forwarded to the inner jb-input and host aria label; see the normal demo. | | message | string | "" | Helper message forwarded to the inner jb-input and host aria description. | | name | string | "" | Form field name forwarded to the inner jb-input. | | placeholder | string | "" | Placeholder forwarded to the inner jb-input; see the RTL example. | | close-button-text | string | localized Close | Text inside the popover close button. | | second-enabled | boolean | true | Enables the second unit. Empty attribute and "true" mean true; "false" means false; see without-second mode. | | leading-zero | boolean | false | Displays picker numbers below 10 with a leading zero; see leading zero. | | optional-units | string | "" | Comma or space separated picker units shown as optional: hour, minute, second; see optional minute. | | show-persian-number | boolean | locale based | Displays Persian digits while .value remains English digits; see Persian number. | | required | boolean \| string | false | Enables required validation. A string value is used as the error message; see validation. | | error | string | "" | External validation error message; see validation. | | disabled | boolean | false | Disables the inner input, prevents input interaction from opening the picker, and sets the disabled state on the host. Empty attribute and "true" mean true; "false" or a removed attribute means false; see disabled. | | readonly | boolean | false | Forwarded to the inner jb-input. | | autocomplete | string | browser default | Forwarded to the inner jb-input. | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | md style defaults | Forwarded to the inner jb-input. |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | string | no | Canonical time value submitted with forms; see controlled value. | | displayValue | string | yes | Formatted time text shown by the inner input, including localized digits. | | initialValue | string | no | Default and reset value. It initializes value until the live value is explicitly set; see initial value. | | isDirty | boolean | yes | true when current value differs from initialValue. | | hour | number | no | Hour value from 0 to 24. | | minute | number | no | Minute value from 0 to 59. | | second | number \| null | no | Second value from 0 to 59, or null when seconds are disabled. | | secondEnabled | boolean | no | Enables or disables the second unit; see without-second mode. | | leadingZero | boolean | no | Displays picker numbers below 10 with a leading zero; see leading zero. | | optionalUnits | Array<'hour' \| 'minute' \| 'second'> | no | Time picker units shown as optional/muted; see optional minute. | | showPersianNumber | boolean | no | Displays Persian digits in the input and picker; see Persian number. | | isOpen | boolean | no | Opens or closes the internal time picker popover. | | required | boolean | no | Enables required validation; see validation. | | disabled | boolean | no | Enables or disables the inner input and host disabled state; see disabled. | | validation | ValidationHelper<ValidationValue> | yes | Validation helper from jb-validation; set validation.list for custom rules. | | validationMessage | string | yes | Current validation message from ElementInternals. |

Methods

| name | returns | description | | --- | --- | --- | | checkValidity() | boolean | Runs validation without showing the error message. Dispatches invalid when invalid; see validation. | | reportValidity() | boolean | Runs validation and shows the first error message. Dispatches invalid when invalid; see validation. | | reset() | void | Restores initialValue and clears displayed validation. | | open() | void | Opens the internal time picker popover. | | close() | void | Closes the internal time picker popover. | | focus() | void | Focuses the inner jb-input; see keyboard and picker. | | addHour(interval) | void | Adds interval to the hour value. Use a negative number to subtract; see time editing. | | addMinute(interval) | void | Adds interval to the minute value. Use a negative number to subtract; see time editing. | | addSecond(interval) | void | Adds interval to the second value. Use a negative number to subtract; see time editing. | | clearValidationError() | void | Clears the visible validation error. |

Events

| event | description | | --- | --- | | load | Dispatched from connectedCallback before initialization; see the event demo. | | init | Dispatched from connectedCallback after initialization; see the event demo. | | input | Dispatched after user input changes the time value; see events. | | beforeinput | Re-dispatched from the inner input before user input is applied; see events. | | change | Dispatched when the committed time value changes after blur or picker interaction; see events. | | focus | Re-dispatched when the inner input receives focus; see events. | | blur | Re-dispatched when the inner input loses focus; see events. | | keydown | Re-dispatched from the inner input; see events. | | keyup | Re-dispatched from the inner input; see events. | | keypress | Re-dispatched from the inner input; see events. | | enter | Dispatched when Enter is pressed; see the Enter event demo. | | invalid | Dispatched when validation fails; see validation. |

Value

Use .value for the canonical English-digit time; see the value demo and hour/minute-only demo.

const timeInput = document.querySelector('jb-time-input');

timeInput.value = '14:34:13';
console.log(timeInput.value); // "14:34:13"
console.log(timeInput.hour); // 14
console.log(timeInput.minute); // 34
console.log(timeInput.second); // 13

For hour/minute-only input, disable seconds and use HH:mm.

<jb-time-input second-enabled="false" value="14:34"></jb-time-input>

timeInput.secondEnabled = false;
timeInput.value = '14:34';

Keyboard and picker

Focus opens the picker, while ArrowUp/ArrowDown and the addHour/addMinute/addSecond methods adjust the active unit; see the normal picker demo.

When the input is focused, the time picker opens in a popover. Use ArrowUp and ArrowDown to change the time unit at the current caret position.

timeInput.addHour(1);
timeInput.addMinute(-5);
timeInput.addSecond(10);

Disabled state

Use disabled to prevent focus, editing, picker opening, and user-generated value changes; see the disabled demo.

Use the disabled attribute or property to prevent focus, editing, picker opening, and user-generated value changes.

<jb-time-input label="Time" value="12:34:56" disabled></jb-time-input>

timeInput.disabled = true;

Validation

Use required, error, and validation.list for validation; see the validation demo.

jb-time-input uses jb-validation. Custom validators receive value, displayValue, and valueObject.

const timeInput = document.querySelector('jb-time-input');

timeInput.validation.list = [
  {
    validator: ({ valueObject }) => valueObject.hour >= 9 && valueObject.hour <= 17,
    message: 'Time must be during working hours',
  },
  {
    validator: ({ valueObject }) => valueObject.minute >= 30,
    message: 'Minute must be 30 or later',
  },
];

Display options

Use leadingZero, optionalUnits, and showPersianNumber to control picker presentation; see leading zero, optional units, and Persian digits.

<jb-time-input
  leading-zero
  optional-units="second"
  show-persian-number
></jb-time-input>

timeInput.leadingZero = true;
timeInput.optionalUnits = ['second'];
timeInput.showPersianNumber = true;

optionalUnits only makes picker units visually muted. It does not remove a unit or change .value.

CSS parts and variables

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

jb-time-input composes jb-input, jb-popover, jb-time-picker, and jb-button. Style the exported close-button part with --jb-button-* variables instead of the removed --jb-time-input-close-button-* variables.

Accessibility notes

• The component is form-associated and submits .value.
• label maps to host aria label and the inner jb-input label.
• message maps to host aria description and the inner helper message.
• disabled disables the nested native input and exposes the host disabled custom state.
• The inner input uses inputmode="none" and virtualkeyboardpolicy="manual" to favor the custom time editing UI.

Related Docs

• See jb-time-input/react if you want to use this component in React.
• See jb-input, jb-time-picker, jb-popover, and jb-button for composed component APIs.
• 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-input once before using <jb-time-input>.
• Use .value for the canonical submitted value: HH:mm:ss when seconds are enabled, HH:mm when seconds are disabled.
• Use second-enabled="false" or secondEnabled = false before setting an hour/minute-only value.
• Use validation.list for custom validation; validators receive { value, displayValue, valueObject }.
• Use show-persian-number only for display. .value remains English digits.
• Use optional-units only for visual emphasis in the picker.
• Use disabled as a boolean property in JavaScript; in markup, use disabled, disabled="true", or remove the attribute to enable the input.
• 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-input tag name to JBTimeInputWebComponent.