Skip to main content

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, and step when 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​

SlotRequiredDescription
labelYesVisible label text for the timepicker.
helper-Helper text rendered below the input.

Props​

PropTypeDefaultDescription
idstring-Associates the control with its label. Auto-generated when omitted.
valuestring-Pre-filled time value in HH:MM format.
minstring-Minimum selectable time in HH:MM format.
maxstring-Maximum selectable time in HH:MM format.
stepnumber-Step in seconds for the native picker.
is_disabledboolean-Disables the control.
is_requiredboolean-Marks the control as required.
is_invalidboolean-Marks the control as invalid. Renders aria-invalid="true" when set.
helper_idstring-ID of the helper element; the control gets aria-describedby pointing to it.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.

Attributes​

AttributeSet byRequiredDescription
data-timepickerConsumerYesMarks a time input eligible for enhancement; a mode attribute (fields, step, min, or max) selects the behavior.
data-timepicker-fieldsConsumer-Opts in to split-fields mode. Value is a space-separated list of fields to render (e.g. "hours minutes period").
data-timepicker-stepConsumer-Step in minutes for the stepped enhancement mode. Defaults to "30".
data-timepicker-minConsumer-Minimum selectable time in HH:MM (stepped and split modes). Defaults to "00:00".
data-timepicker-maxConsumer-Maximum selectable time in HH:MM (stepped and split modes). Defaults to "23:59".
data-timepicker-hours-labelConsumer-Visually-hidden label for the hours select in split-fields mode. Defaults to "Hours".
data-timepicker-minutes-labelConsumer-Visually-hidden label for the minutes select in split-fields mode. Defaults to "Minutes".
data-timepicker-minutes-stepConsumer-Step in minutes for the minutes select in split-fields mode. Defaults to "1".
data-timepicker-period-labelConsumer-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​

  • textfield - base styling for the input field
  • group - arranges the enhanced fields in one row

Progressive enhancement​

  • No JS: native <input type="time"> with the browser's built-in picker, min/max/step/required validation, 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