Time Picker

BEEQ Time-picker component overview — Time-picker component overview

Time pickers combine locale-ordered hour, minute, and second segments with a panel of scrollable columns. People can type a time directly or pick it from the panel, and the component keeps the value in a predictable 24-hour format.

Use a time picker when people need to set a time of day. To pick a date and a time together, pair it with a date picker. For a short list of fixed slots, such as three delivery windows, a select or radio group is clearer.

When to use

Use time pickers when

People need to set a specific time of day, such as a meeting start or an alarm
The time must follow local conventions, like segment order and AM/PM labels
You need to limit times with business hours or fixed intervals
Typing and picking should both be quick and error-free

Do not use time pickers when

Only a handful of fixed time slots are available
People need to enter a duration longer than a day
The value is a relative time, like “in 2 hours”
An approximate time of day, like “morning”, is enough

Patterns

Anatomy

The time picker pairs a labeled, segmented field with a panel of columns, one per time unit. The example uses second precision, a 12-hour clock, and a prefix icon to show every part. Keep the label specific and let the locale decide the segment order and labels.

Part	Element	Description
1	Label	Describes which time the field asks for (`label` slot)
2	Prefix	Optional icon or text before the time segments (`prefix` slot)
3	Time segments	The hour, minute, second, and AM/PM controls people focus and edit, ordered for the active locale
4	Clear button	Removes the current value; hidden with `disable-clear`
5	Clock trigger	Opens the panel; its icon can be replaced with the `suffix` slot
6	Panel	The surface that holds the columns and the footer actions
7	Column	A scrollable list of options for one time unit, under a header that names it and stays in place while the list scrolls
8	Selected option	The current hour, minute, second, or period, shown with selected styling
9	Now button	Picks the current time, rounded down to the step; hidden with `disable-now`
10	OK button	Confirms the selection and closes the panel

Design guidelines

Pick the right precision

Start with the default minute precision. Use hour for coarse slots, such as opening hours, and second only when seconds matter, such as lap times or logs.

Let the locale drive the format

Set locale to the product locale, so segment order, separators, and AM/PM labels match what people expect. The clock is 24-hour by default; set hour-format="12" when people expect a 12-hour clock.

Constrain the choices

Apply min, max, and step values when business rules are known. Options outside the rules are disabled in the panel, and typed values are clamped when focus leaves the field.

Use steps that divide evenly into the unit, such as 5, 10, 15, or 30 minutes, so the options stay predictable and easy to scan.

Keep the clock trigger visible. It signals that a panel is available and gives pointer users a faster way to pick a time.

Usage

Default

Use the default configuration when people need to set an hour and minute. Click the field or the clock icon to open the panel, or type the time directly.

The value attribute, min, and max always use a 24-hour wire format, whatever the display: HH:mm at minute precision, HH:00 at hour precision, and HH:mm:ss at second precision.A locale-derived format hint, such as hh:mm, shows the expected layout before entry starts. On focus, one segment is active. Type digits to replace that segment, use ArrowLeft and ArrowRight to move, Home and End to reach the first or last segment, ArrowUp and ArrowDown to change a value, and Backspace or Delete to clear a segment. For AM/PM, type A or P. Paste is not supported.

Options

Precision

Use precision to choose the smallest unit people edit and submit. The field and the panel only show the matching segments and columns. At hour precision on a 24-hour clock, the panel adds a disabled minute column fixed at 00, so it reads as a time.

12-hour and 24-hour clock

The clock is 24-hour by default, whatever the locale. Set hour-format="12" for a 12-hour clock with an AM/PM segment. The submitted value stays in 24-hour format.

Locale

Use locale to set the segment order, separators, AM/PM labels, and column headers. Some locales place the period before the hour, and the panel columns follow the same order. The examples set hour-format="12" where the locale usually shows a 12-hour clock.

Labels

Use labels to change the column headers, AM/PM labels, button text, and accessible names, for example to translate them. Pass an object, or a JSON string through the HTML attribute. Every key is optional: hour, minute, second, am, and pm default to the locale names, period defaults to the AM and PM labels joined by a slash, and the rest default to English.

Key	Used for	Default
`hour`	Hour column header and hour segment name	Locale name, e.g. `hour`
`minute`	Minute column header and minute segment name	Locale name, e.g. `minute`
`second`	Second column header and second segment name	Locale name, e.g. `second`
`period`	AM/PM column header and AM/PM segment name	`am` and `pm` joined by a slash
`am`	Morning period in the field and the panel	Locale label, e.g. `am`
`pm`	Afternoon period in the field and the panel	Locale label, e.g. `pm`
`now`	”Now” button text	`"Now"`
`clear`	Clear button name	`"Clear"`
`confirm`	Confirm button text	`"OK"`
`openPanel`	Clock trigger button name	`"Open time picker"`
`panelLabel`	Panel name	`"Choose time"`

Minimum and maximum time

Use min and max to set the earliest and latest selectable times. Options outside the range are disabled in the panel, and the “Now” button is disabled when the current time is out of range. If min is later than max, both are ignored.

Steps

Use hour-step, minute-step, and second-step to show options at fixed intervals. Typed values that fall between steps are kept but flagged as invalid, and “Now” rounds down to the nearest step.

Require confirmation

With require-confirm, panel picks, including “Now”, stay a draft until people press OK or Enter. Escape, an outside click, or moving focus away discards the draft. Values typed in the field are always committed right away.

Without the Now button

Set disable-now to hide the “Now” button when the current time isn’t a meaningful choice, such as for reminders set for later in the day. The OK button is always shown.

Prefix and suffix

Use the prefix slot to add context before the value. The suffix slot replaces the clock icon inside the trigger button, so set labels.openPanel to keep the button name accurate.

Without the clear button

Set disable-clear to hide the clear button when the field should always hold a value.

Disabled and read-only

Use disabled when the time isn’t available for editing and shouldn’t be submitted. Use readonly when people should see and submit the value but not change it: the segments stay focusable, and the panel doesn’t open.

Validation states

Use validation-status when the field should show immediate visual feedback after validation.

Form integration

bq-time-picker submits its current value with the form, in 24-hour format. Use required and form-validation-message when the time is mandatory; the custom message also applies to incomplete, out-of-range, and off-step values.

A partly filled field becomes invalid when focus leaves it, even when the picker is optional. The draft stays visible and the last committed value is preserved, but native form validation blocks submission until people complete the time, pick one from the panel, or clear the field.

When focus leaves the field, complete times outside min or max are clamped to the nearest bound. A disabled time picker is excluded from form data; a read-only one is still submitted.

Best practices

DoWrite labels that name the moment, such as “Departure time” or “Meeting starts”, so people know which time they are setting.

Don’tDo not rely on the format hint alone to explain the field. Always provide a visible label.

DoMatch precision to the task. Most scheduling needs hours and minutes only; add seconds only for durations or precise logs.

Don’tDo not ask for seconds when nobody will use them. Every extra segment adds typing and scanning effort.

DoSet min, max, and step values when business rules are known, so unavailable times are disabled before people pick them.

Don’tDo not mix clocks across a product. Pick the hour-format your audience expects and use it for every time picker.

DoUse require-confirm when a picked time triggers an expensive or irreversible action, such as rescheduling a booking.

Don’tDo not use a time picker for durations longer than a day or for picking a date and time together.

Accessibility

bq-time-picker is form-associated and delegates focus, so it participates in native forms and moves focus into its segmented field when the component receives focus.
The segmented field is a labelled group described by the expected format and, when a constraint fails, by the validation message. Each hour, minute, second, and AM/PM control is a spinbutton with its own label, limits, value text, and roving tabindex, and exposes aria-required when the field is required.
Each segment sets aria-invalid="true" for validationStatus="error" and native constraint failures, such as a missing required value or an incomplete, out-of-range, or off-step time. aria-readonly and aria-disabled reflect the readonly and disabled states.
The panel carries role="dialog" and is named by labels.panelLabel (“Choose time” by default). The panel isn’t modal.
Each column is a listbox labelled by its visible header (aria-labelledby), so the spoken name matches what people see. Options expose aria-selected, and options outside min, max, or the steps expose aria-disabled="true".
The component announces the selected time, or that no time is selected, when focus enters the field.
Press Alt+ArrowDown in the field, or Tab to the clock icon and press Enter or Space, to open the panel and move focus into it. Clicking the field opens the panel while keeping focus on the segment.
In the panel, ArrowUp and ArrowDown move between options, Home and End jump to the first or last option, PageUp and PageDown move faster, and ArrowLeft and ArrowRight switch columns. Enter or Space picks an option, and Escape closes the panel and returns focus to the field.
In readonly mode the segments stay focusable so screen reader users can read the value, but they can’t be edited and the panel doesn’t open.
Always provide a visible label through the label slot, so the field has a programmatic name.
When you translate the interface, translate labels too: segment names, button names and the panel name come from it.
Validation states should never rely on color alone. Pair validationStatus with visible error text so screen reader users receive the same feedback as sighted users.

API reference

Properties

Property	Attribute	Description	Type	Default
`autofocus`	`autofocus`	If `true`, the Time picker field will be focused on component render	`boolean`	`false`
`disableClear`	`disable-clear`	If `true`, the clear button won’t be displayed	`boolean`	`false`
`disableNow`	`disable-now`	If `true`, the panel “Now” button won’t be displayed	`boolean`	`false`
`disabled`	`disabled`	Indicates whether the Time picker is disabled or not	`boolean`	`false`
`distance`	`distance`	Distance (gutter) between the Time picker panel and the field	`number`	`8`
`form`	`form`	The ID of the form the field belongs to	`string`	`undefined`
`formValidationMessage`	`form-validation-message`	Native form validation message	`string`	`undefined`
`hourFormat`	`hour-format`	The clock used by the field and the panel: 24-hour (`"24"`) or 12-hour with an AM/PM period (`"12"`). It doesn’t depend on the `locale`	`"12" \| "24"`	`"24"`
`hourStep`	`hour-step`	Step between selectable hours	`number`	`1`
`labels`	`labels`	Text of the column headers, AM/PM labels, buttons and accessible names, as an object or a JSON string. Missing keys fall back to the `locale` names or English text. See Labels	`TTimePickerLabels \| string`	`undefined`
`locale`	`locale`	Locale used for the field layout, separators, column headers and day period labels. The clock is set by `hour-format`	`Locale \| readonly (string \| Locale)[] \| string`	`"en-GB"`
`max`	`max`	Latest selectable time, in 24-hour format (`HH:mm` or `HH:mm:ss`). Ignored, together with `min`, when it is earlier than `min`	`string`	`undefined`
`min`	`min`	Earliest selectable time, in 24-hour format (`HH:mm` or `HH:mm:ss`). Ignored, together with `max`, when it is later than `max`	`string`	`undefined`
`minuteStep`	`minute-step`	Step between selectable minutes	`number`	`1`
`name`	`name`	Name submitted with the form data (required)	`string`	`undefined`
`open`	`open`	If `true`, the panel is visible	`boolean`	`false`
`panelHeight`	`panel-height`	Overrides the height of the Time picker panel	`string`	`"auto"`
`placement`	`placement`	Position of the Time picker panel	`"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"`	`"bottom-end"`
`precision`	`precision`	Smallest unit edited and submitted: `hour` → `HH:00`, `minute` → `HH:mm`, `second` → `HH:mm:ss`	`"hour" \| "minute" \| "second"`	`"minute"`
`readonly`	`readonly`	If `true`, the value can be read and submitted but not changed	`boolean`	`false`
`requireConfirm`	`require-confirm`	If `true`, picks made in the panel (including “Now”) are a draft until confirmed with the OK button or Enter. The field keeps showing the committed value until then. Escape or an outside click discards the draft	`boolean`	`false`
`required`	`required`	Whether a value must be entered before submitting the form	`boolean`	`false`
`secondStep`	`second-step`	Step between selectable seconds	`number`	`1`
`skidding`	`skidding`	Skidding between the panel and the field	`number`	`0`
`strategy`	`strategy`	Positioning strategy for the panel	`"absolute" \| "fixed"`	`"fixed"`
`validationStatus`	`validation-status`	Validation state applied to the field	`"error" \| "none" \| "success" \| "warning"`	`"none"`
`value`	`value`	The selected time, in 24-hour format: `HH:mm` (`HH:00` at hour precision) or `HH:mm:ss` at second precision	`string`	`undefined`

Events

Event	Description	Type
`bqBlur`	Fired when focus leaves the Time picker. Moving focus between the field and the panel does not fire it	`CustomEvent<HTMLBqTimePickerElement>`
`bqChange`	Fired when the value is committed or cleared	`CustomEvent<{ value: string; el: HTMLElement }>`
`bqClear`	Fired when the value is cleared	`CustomEvent<HTMLBqTimePickerElement>`
`bqFocus`	Fired when focus enters the Time picker. Moving focus between the field and the panel does not fire it	`CustomEvent<HTMLBqTimePickerElement>`

In React, prefix events with on: onBqBlur, onBqChange, onBqClear, onBqFocus.
In Angular, use the event binding syntax: (bqBlur), (bqChange), (bqClear), (bqFocus).
In Vue, use the @ shorthand: @bqBlur, @bqChange, @bqClear, @bqFocus.

Methods

Method	Description	Signature
`clear()`	Clears the value and any pending validation state, then emits `bqClear`. Does nothing when the component is disabled or read-only	`clear() => Promise<void>`

Slots

Slot	Description
`label`	Label displayed above the field
`prefix`	Optional content rendered before the value
`suffix`	Replaces the icon inside the clock trigger button; defaults to a clock icon. Use `labels.openPanel` to name the button
`clear-icon`	Replaces the default clear icon

Shadow parts

Part	Description
`base`	Base wrapper for the component
`label`	Label slot container
`control`	Field control wrapper
`prefix`	Prefix slot container
`suffix`	Clock trigger button that hosts the suffix slot
`input`	Segmented time field group
`segment`	Editable hour, minute, second, or AM/PM segment
`segment-literal`	Locale-derived separator between time segments
`clear-btn`	Clear button
`time-trigger`	Clock icon trigger button
`button`	Any button rendered by the component
`panel`	Dropdown panel container
`container`	Panel content wrapper
`columns`	Wrapper of the panel columns
`column`	Scrollable list of options (hours, minutes, seconds, or AM/PM)
`column-header`	Header above a column; it stays in place while the column scrolls
`option`	Any option inside a column
`option-selected`	Selected option of a column
`footer`	Panel footer
`now-btn`	”Now” button
`confirm-btn`	Confirm (OK) button

CSS custom properties

Show CSS variables

Variable	Description	Default
`--bq-time-picker--background-color`	Time picker background color	`var(--bq-ui--primary)`
`--bq-time-picker--border-color`	Time picker border color	`var(--bq-stroke--tertiary)`
`--bq-time-picker--border-color-disabled`	Time picker border color when disabled	`var(--bq-stroke--secondary)`
`--bq-time-picker--border-color-focus`	Time picker border color on focus	`var(--bq-stroke--brand)`
`--bq-time-picker--border-color-danger`	Time picker border color when the validation status is `error`	`var(--bq-stroke--danger)`
`--bq-time-picker--border-color-success`	Time picker border color when the validation status is `success`	`var(--bq-stroke--success)`
`--bq-time-picker--border-color-warning`	Time picker border color when the validation status is `warning`	`var(--bq-stroke--warning)`
`--bq-time-picker--border-radius`	Time picker border radius	`var(--bq-radius--s)`
`--bq-time-picker--border-style`	Time picker border style	`solid`
`--bq-time-picker--border-width`	Time picker border width	`1px`
`--bq-time-picker--column-gap`	Space between the panel columns	`var(--bq-spacing-xs2)`
`--bq-time-picker--column-header-text-color`	Text color of the column headers	`var(--bq-text--secondary)`
`--bq-time-picker--column-height`	Height of the scrollable panel columns	`15rem`
`--bq-time-picker--column-width`	Width of a panel column	`3.5rem`
`--bq-time-picker--divider-color`	Color of the lines between the panel columns and above the footer	`var(--bq-stroke--primary)`
`--bq-time-picker--gap`	Gap between field content and prefix/suffix	`var(--bq-spacing-xs)`
`--bq-time-picker--icon-size`	Prefix/suffix/clear icon size	`1.5rem`
`--bq-time-picker--label-margin-bottom`	Space below the label	`var(--bq-spacing-xs)`
`--bq-time-picker--label-text-color`	Label text color	`var(--bq-text--primary)`
`--bq-time-picker--label-text-size`	Label text size	`0.875rem`
`--bq-time-picker--option-background-hover`	Hover background of a column option	`var(--bq-ui--secondary)`
`--bq-time-picker--option-background-selected`	Background of the selected column option	`var(--bq-ui--brand)`
`--bq-time-picker--option-height`	Height of a column option	`2.5rem`
`--bq-time-picker--option-width`	Width of a column option	`3rem`
`--bq-time-picker--option-radius`	Border radius of a column option	`var(--bq-radius--xs)`
`--bq-time-picker--option-text-selected`	Text color of the selected column option	`var(--bq-text--on-brand, var(--bq-text--alt))`
`--bq-time-picker--padding-end`	Field padding end	`var(--bq-spacing-m)`
`--bq-time-picker--padding-start`	Field padding start	`var(--bq-spacing-m)`
`--bq-time-picker--paddingY`	Field vertical padding	`var(--bq-spacing-s)`
`--bq-time-picker--text-color`	Field text color	`var(--bq-text--primary)`
`--bq-time-picker--text-placeholder-color`	Placeholder text color	`var(--bq-text--secondary)`
`--bq-time-picker--text-size`	Field text size	`1rem`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore time picker variants, constraints, locales, and panel behavior in Storybook.

Source code

Browse the component implementation, styles, and tests on GitHub.

Actions

Data Display

Feedback

Form Controls

Layout

Navigation

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Options

Precision

12-hour and 24-hour clock

Locale

Labels

Minimum and maximum time

Steps

Require confirmation

Without the Now button

Prefix and suffix

Without the clear button

Disabled and read-only

Validation states

Form integration

Best practices

Accessibility

API reference

Properties

Events

Methods

Slots

Shadow parts

CSS custom properties

Resources

Interactive playground

Source code

​When to use

​Patterns

​Anatomy

​Design guidelines

​Usage

​Default

​Options

​Precision

​12-hour and 24-hour clock

​Locale

​Labels

​Minimum and maximum time

​Steps

​Require confirmation

​Without the Now button

​Prefix and suffix

​Without the clear button

​Disabled and read-only

​Validation states

​Form integration

​Best practices

​Accessibility

​API reference

​Properties

​Events

​Methods

​Slots

​Shadow parts

​CSS custom properties

​Resources

Interactive playground

Source code

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Options

Precision

12-hour and 24-hour clock

Locale

Labels

Minimum and maximum time

Steps

Require confirmation

Without the Now button

Prefix and suffix

Without the clear button

Disabled and read-only

Validation states

Form integration

Best practices

Accessibility

API reference

Properties

Events

Methods

Slots

Shadow parts

CSS custom properties

Resources