Timepicker
Time input with optional progressive enhancement. Base uses a native <input type="time"> and the browser's built-in picker. Two enhancement modes opt in via data attributes: a stepped mode (single <select> populated with time options at a fixed step) and a split fields mode (separate hours, minutes, and optional AM/PM selects composed into a single time value on submit). Mirrors the datepicker pattern for consistency.
Usage
When to use
- Capturing a time-of-day value (meeting start, launch window, shift handover)
- When you want the native browser picker on the base
- When you need a constrained list of time options (stepped select) or segmented entry on touch devices (split fields)
When not to use
- Date + time together - use a datetime control
- Duration (e.g. "30 minutes") - use a number input with a unit
- Free-form time ranges - compose two timepickers
Do
- Pair the input with a visible
<label> - Set
min,max, andstepwhen the acceptable range is known - Use stepped mode for small stepped ranges (e.g. 30-minute increments)
- Use split fields mode when users type the value and a picker UI would be awkward
Don't
- Hide the native base behavior - it should still submit a valid time in every mode
- Omit the label or rely on placeholder text
- Use split fields without per-field labels
API
Slots
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text for the timepicker. |
helper | - | Helper text rendered below the input. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | - | Associates the control with its label. Auto-generated when omitted. |
value | string | - | Pre-filled time value in HH:MM format. |
min | string | - | Minimum selectable time in HH:MM format. |
max | string | - | Maximum selectable time in HH:MM format. |
step | number | - | Step in seconds for the native picker. |
is_disabled | boolean | - | Disables the control. |
is_required | boolean | - | Marks the control as required. |
is_invalid | boolean | - | Marks the control as invalid. Renders aria-invalid="true" when set. |
helper_id | string | - | ID of the helper element; the control gets aria-describedby pointing to it. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-timepicker | Consumer | Yes | Marks a time input eligible for enhancement; a mode attribute (fields, step, min, or max) selects the behavior. |
data-timepicker-fields | Consumer | - | Opts in to split-fields mode. Value is a space-separated list of fields to render (e.g. "hours minutes period"). |
data-timepicker-step | Consumer | - | Step in minutes for the stepped enhancement mode. Defaults to "30". |
data-timepicker-min | Consumer | - | Minimum selectable time in HH:MM (stepped and split modes). Defaults to "00:00". |
data-timepicker-max | Consumer | - | Maximum selectable time in HH:MM (stepped and split modes). Defaults to "23:59". |
data-timepicker-hours-label | Consumer | - | Visually-hidden label for the hours select in split-fields mode. Defaults to "Hours". |
data-timepicker-minutes-label | Consumer | - | Visually-hidden label for the minutes select in split-fields mode. Defaults to "Minutes". |
data-timepicker-minutes-step | Consumer | - | Step in minutes for the minutes select in split-fields mode. Defaults to "1". |
data-timepicker-period-label | Consumer | - | Visually-hidden label for the AM/PM select in split-fields mode. Defaults to "AM/PM". |
Examples
Sizes
Sm, default, and lg variants stacked vertically. Font size and padding scale together.
Native
Base <input type="time"> with browser picker, no JS.
Stepped
Single <select> populated with time options at a fixed step via data-timepicker-step/min/max.
Split fields
Hours / minutes fields composed into a time value via data-timepicker-fields.
Split fields with period
Hours / minutes / AM-PM.
Disabled
Disabled state across all modes.
Accessibility
- WCAG 2.2 AA
- Every timepicker has a programmatic label
- Stepped select exposes its options to assistive technology via the native
<select>semantics - Split fields are grouped in a
<fieldset>with a<legend>describing the group, and each field has its own label - Full keyboard operation: Tab between fields, arrow keys step values where applicable, native select interactions follow the platform
- Focus indication is visible in every mode
Dependencies
Progressive enhancement
- No JS: native
<input type="time">with the browser's built-in picker,min/max/step/requiredvalidation, and disabled state - With JS: opt into stepped or split fields mode via data attributes. In the enhanced (stepped and split fields) modes, the form submits a hidden
<input type="time">value so server-side handling is identical to native mode. Native mode submits only the original<input type="time">control - How to enable: add the relevant
data-timepicker-*attributes to the input; the timepicker helper script picks up both modes
Related
- datepicker - sibling pattern for dates
- textfield - base input styling