toc

Time picker

Time pickers let people choose an hour and minute on a clock dial, or type them into fields.

<md-gb-time-picker value="07:00"></md-gb-time-picker>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-time-picker.json (setup)

Usage guidelines

Link to “Usage guidelines”

Dial or input. The dial is quick for picking an approximate time, and typing is faster for an exact one. People can switch between them unless you hide the toggle.
Inline or modal. Show the picker inline in a form, or as a modal when it opens from a field or button.
Match the locale. The picker follows the 12 or 24 hour clock of its locale. Set hour-cycle to force one.

Anatomy

Link to “Anatomy”

A time picker has a headline, the hour and minute selectors, an AM or PM toggle in 12 hour mode, a dial, and the actions.

<md-gb-time-picker value="09:30"></md-gb-time-picker>

Examples

Link to “Examples”

Link to “Inline and modal”

Add modal to show the picker in a dialog with a scrim. Open it with show(). It fires change when a time is confirmed and cancel when it is dismissed.

HTML

<md-gb-button id="set-alarm">Set alarm</md-gb-button>
<md-gb-time-picker id="alarm" modal headline="Set alarm"></md-gb-time-picker>
<output id="time" for="alarm"></output>

const alarm = document.querySelector('#alarm');
document.querySelector('#set-alarm').addEventListener('click', () => {
  alarm.show();
});
alarm.addEventListener('change', (event) => {
  document.querySelector('#time').textContent = event.target.value;
});

Input mode

Link to “Input mode”

Set mode="input" to start with hour and minute fields instead of the dial. Add hide-mode-toggle to remove the switch between the two.

<md-gb-time-picker mode="input" value="07:00"></md-gb-time-picker>

Hour cycle

Link to “Hour cycle”

Set hour-cycle to 12 or 24. The value is always a 24 hour HH:MM string.

<md-gb-time-picker hour-cycle="24" value="20:00"></md-gb-time-picker>

Orientation

Link to “Orientation”

The dial sits below the time selectors (vertical), except in short landscape windows, where it moves beside them (horizontal). Set orientation to choose one.

<md-gb-time-picker orientation="horizontal" value="07:00"></md-gb-time-picker>

Density

Link to “Density”

Set density from 0 (default) to -3 to make the picker more compact.

<md-gb-time-picker mode="input" density="-3" value="07:00"></md-gb-time-picker>

Accessibility

Link to “Accessibility”

Input mode is an alternative to the dial, and every control has a label. Localize the labels with attributes such as select-hour-label, hour-label, cancel-label and confirm-label.
A modal picker is a <dialog>: focus moves into it and returns to the opener on close, and Escape cancels.
In the dial, the arrow keys change the selected hour or minute.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked93% tokens

208 of 342 buildable spec units are tested, 2 are excluded with a written reason and 0 are uncovered (the target is 0). 88 of 95 token declarations match the spec (93%), and 7 have no spec token.

time-pickers on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

@starting-style (opens in a new tab) Newly available degrades safely where it is missing
Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
scrollbar-color (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-gutter (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing
user-select (opens in a new tab) Limited availability used inside an @supports guard

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonDialog (Modal)

Roles the component renders: button (opens in a new tab), dialog (opens in a new tab), group (opens in a new tab), radio (opens in a new tab), radiogroup (opens in a new tab), slider (opens in a new tab), textbox (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Dialog (Modal) (opens in a new tab), Radio Group (opens in a new tab), Slider (opens in a new tab).

2 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse99 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Elements with visible text labels do not have matching accessible names.
Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-time-picker>

Link to “<md-gb-time-picker>”

A Material Design time picker component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`cancelLabel` Cancel action label.	`cancel-label`	`string`	`'Cancel'`
`confirmLabel` OK action label.	`confirm-label`	`string`	`'OK'`
`density` The density, from 0 (default) to -3 (time-pickers.md "Density", "High-density time picker"). Each step down removes 4px from the time selectors (80px), input fields (72px), the period selector (which follows their height) and the dial (256px); the time selectors, fields and dial labels stay at least 48px. The horizontal layout, used when the viewport is short, keeps the full-size dial ("Don't apply density to the time picker dial when the viewport is constrained. Instead, use an input picker"). Values are clamped to that range.	`density`	`Density`
`dialModeLabel` Accessible label of the mode toggle in input mode.	`dial-mode-label`	`string`	`'Switch to clock mode'`
`headline` The headline. Defaults to "Select time" (dial) or "Enter time" (input).	`headline`	`string`	`''`
`hideActions` Hides the Cancel and OK actions; every change commits the value.	`hide-actions`	`boolean`	`false`
`hideModeToggle` Hides the dial / input mode toggle button.	`hide-mode-toggle`	`boolean`	`false`
`hourCycle` `12` (with an AM/PM period selector), `24`, or `''` (default) to follow the locale's clock (`Intl.DateTimeFormat`).	`hour-cycle`	`TimePickerHourCycle`	`''`
`hourLabel` Hour field label (input mode).	`hour-label`	`string`	`'Hour'`
`inputModeLabel` Accessible label of the mode toggle in dial mode.	`input-mode-label`	`string`	`'Switch to text input mode'`
`locale` The locale used for the 12/24-hour default and the AM/PM labels. Defaults to the browser locale.	`locale`	`string`	`''`
`minuteLabel` Minute field label (input mode).	`minute-label`	`string`	`'Minute'`
`modal` Renders the picker as a modal dialog, shown with `show()` or `open`.	`modal`	`boolean`	`false`
`mode` `dial` (clock dial) or `input` (hour and minute text fields).	`mode`	`TimePickerMode`	`'dial'`
`open` Whether a modal picker is open. Setting it opens or closes the picker.	`open`	`boolean`
`orientation` The dial layout: `vertical`, `horizontal`, or `''` (default) to pick one from the viewport (horizontal in short landscape viewports).	`orientation`	`""`	TimePickerOrientation
`periodLabel` Accessible label of the period selector.	`period-label`	`string`	`'Select AM or PM'`
`quick` Skips transitions.	`quick`	`boolean`	`false`
`required` Whether a time is required: with no time the picker is invalid (`valueMissing`) and blocks the form's submit.	`required`	`boolean`	`false`
`selectHourLabel` Accessible label of the hour selector and the dial in hour mode.	`select-hour-label`	`string`	`'Select hour'`
`selection` Which part of the time the dial edits.		`TimePickerSelection`	`'hour'`
`selectMinuteLabel` Accessible label of the minute selector and the dial in minute mode.	`select-minute-label`	`string`	`'Select minutes'`
`value` The committed time as a 24-hour `HH:MM` string (`<input type="time">` format), or `''` when no time is set.	`value`	`string`

Events

Link to “Events”

Event	Description
`cancel` Event	Fired when picking is canceled (Cancel, Escape, scrim click). Cancelable for a modal picker; canceling keeps it open.
`change` Event	Fired when a new `value` is committed (OK, or the end of an interaction with `hide-actions`).
`close` Event	Fired when a modal picker closes.
`input` Event	Fired whenever the picked time changes (dial drag, key, typed digits, period). Read the pending time from `pendingValue`.
`open` Event	Fired when a modal picker opens.

Methods

Link to “Methods”

Method	Description
`cancel` (reason?: string) => void	Discards the pending time and fires `cancel`; a modal picker closes unless the event is canceled (canceling keeps the pending time). What the Cancel action does.
`close` (reason?: string) => Promise<void>	Closes a modal picker without committing. Fires a cancelable `close` event with `detail.reason`, then `closed` after the exit transition.
`confirm` () => void	Commits the pending time to `value` (firing `change` when it differs) and closes a modal picker. What the OK action does.
`show` () => Promise<void>	Opens a modal picker on the committed time, starting with the hours. Fires `open`.
`toggleMode` () => void	Switches between the dial and input modes.

CSS parts

Link to “CSS parts”

Part	Description
`::part(actions)`	The actions row.
`::part(container)`	The picker container (a `<dialog>` when modal).
`::part(dial)`	The clock dial.
`::part(headline)`	The headline.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--clock-dial-color`	Clock dial color.
`--clock-dial-container-size`	Clock dial size.
`--clock-dial-label-text`	Clock dial number typography.
`--clock-dial-selected-label-text-color`	Clock dial number color under the selector handle.
`--clock-dial-selector-center-container-color`	Selector center dot color.
`--clock-dial-selector-center-container-size`	Selector center dot size.
`--clock-dial-selector-handle-container-color`	Selector handle color.
`--clock-dial-selector-handle-container-size`	Selector handle size.
`--clock-dial-selector-track-container-color`	Selector track color.
`--clock-dial-selector-track-container-width`	Selector track width.
`--clock-dial-unselected-label-text-color`	Clock dial number color.
`--container-color`	Container color.
`--container-elevation`	Container elevation (modal).
`--container-padding`	Container padding.
`--container-shape`	Container corner radius.
`--density-step`	Size removed per density step (time selectors, input fields, period selector, dial).
`--headline`	Headline typography.
`--headline-color`	Headline color.
`--period-selector-container-shape`	Period selector corner radius.
`--period-selector-horizontal-container-height`	Horizontal period selector height.
`--period-selector-horizontal-container-width`	Horizontal period selector width.
`--period-selector-label-text`	Period selector typography.
`--period-selector-outline-color`	Period selector outline color.
`--period-selector-outline-width`	Period selector outline width.
`--period-selector-selected-container-color`	Selected period color.
`--period-selector-selected-label-text-color`	Selected period text color.
`--period-selector-unselected-label-text-color`	Unselected period text color.
`--period-selector-vertical-container-height`	Vertical period selector height.
`--period-selector-vertical-container-width`	Vertical period selector width.
`--scrim-color`	Modal scrim color.
`--scrim-opacity`	Modal scrim opacity.
`--time-input-field-container-color`	Input mode field color.
`--time-input-field-container-height`	Input mode field height.
`--time-input-field-container-width`	Input mode field width.
`--time-input-field-focus-container-color`	Focused input mode field color.
`--time-input-field-focus-outline-color`	Focused input mode field outline color.
`--time-input-field-label-text`	Input mode field typography.
`--time-input-field-supporting-text`	Input mode field label typography.
`--time-selector-24h-vertical-container-width`	Hour and minute selector width in the 24-hour vertical layout.
`--time-selector-container-height`	Hour and minute selector height.
`--time-selector-container-shape`	Hour and minute selector corner radius.
`--time-selector-container-width`	Hour and minute selector width.
`--time-selector-label-text`	Hour and minute selector typography.
`--time-selector-selected-container-color`	Selected hour or minute selector color.
`--time-selector-selected-label-text-color`	Selected hour or minute selector text color.
`--time-selector-separator`	Separator typography.
`--time-selector-separator-color`	Separator color.
`--time-selector-unselected-container-color`	Unselected hour or minute selector color.
`--time-selector-unselected-label-text-color`	Unselected hour or minute selector text color.