time-picker

Form-associated time input with combobox text entry, spinbutton dropdown, 12h/24h format, and progressive enhancement over native input[type=time].

Overview

The <time-picker> component wraps a native <input type="time"> and provides a combobox text input with an optional spinbutton dropdown panel. Users can type a time directly (e.g. “2:30pm”, “14:30”, “3pm”) or click the clock icon to adjust via spinbuttons. It supports 12-hour and 24-hour formats, respects min, max, and step constraints from the native input, and participates in form submission via ElementInternals.

Attributes

Attribute Type Default Description
name string — Form field name for submission.
data-format string locale Force 12h or 24h display. Defaults to the user’s locale preference.
disabled boolean false Disables the picker.
required boolean false Marks the field as required for form validation.

Native input attributes

The following attributes are read from the child <input type="time">:

Attribute Effect
value Initial time in HH:MM or HH:MM:SS format.
min Earliest allowed time (e.g. 09:00).
max Latest allowed time (e.g. 17:00).
step Step increment in seconds. Use 900 for 15-minute intervals. Values under 60 show a seconds spinner.

12-Hour Format

Set data-format="12h" to display an AM/PM toggle alongside the hour and minute spinners.

Step Intervals

The step attribute on the native input controls minute increments. For example, step="900" restricts minutes to 15-minute intervals (0, 15, 30, 45).

Form Integration

The component is form-associated via ElementInternals and works inside <form-field> for validation messaging.

Keyboard

Text input

Key Action
Enter Parse and commit the typed time value.
Arrow Down Open the spinbutton panel and focus the first spinner.
Escape Close the panel and revert display to the current value.
Tab Close the panel and move focus to the next element.

Spinbutton panel

Key Action
Arrow Up / Arrow Down Increment / decrement the focused segment.
Arrow Left / Arrow Right Move focus between segments (hours, minutes, seconds, AM/PM).
Page Up / Page Down Increment / decrement by a larger step.
Home / End Jump to minimum / maximum value for the segment.
0–9 Direct number entry into the focused segment.
Escape Close the panel and return focus to the text input.

Events

Event Detail Description
time-picker:change { value, hours, minutes, seconds } Fired when the time value changes.

Accessibility

The text input uses role="combobox" with aria-expanded and aria-controls linked to the spinbutton panel. Each time segment in the panel uses role="spinbutton" with aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext. The increment/decrement buttons are aria-hidden since keyboard interaction is handled on the spinbutton element itself.
↑