Time Picker
Material Design 3 time picker for selecting a single time with a clock interface. Not intended for duration editing or multi-time scheduling workflows.
Basic Usage
Use a time picker to choose a time quickly. The clock interaction helps users select valid values with less formatting friction.
<ds-time-picker label="Select time"></ds-time-picker>
Initial Value
Provide an initial value in HH:mm (24-hour) format.
<ds-time-picker label="Meeting time" value="14:30"></ds-time-picker>
Variants
Switch between 12-hour and 24-hour formats.
Format Options
<ds-time-picker label="12-hour format" value="14:30" hour12="true"></ds-time-picker> <ds-time-picker label="24-hour format" value="14:30" hour12="false"></ds-time-picker>
States
Use disabled or required where appropriate.
<ds-time-picker label="Disabled" value="09:00" disabled></ds-time-picker> <ds-time-picker label="Required" required></ds-time-picker>
Interactive Example
Track open, close, and change events.
API
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
name |
string | "" | Form field name. The 24-hour time is submitted under it; without a name the field is left out. |
value |
string | "" | Selected time in HH:mm format (24-hour) |
label |
string | "Select time" | Label text for the input field |
disabled |
boolean | false | Disables the time picker |
required |
boolean | false | Marks the field as required |
hour12 |
boolean | true | Use 12-hour format with AM/PM |
locale |
string | "en-US" | Locale for time formatting |
Forms
Submits the time as HH:mm (24-hour, whatever the display format), "" when empty, like a native time input. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.
Properties
| Property | Type | Description |
|---|---|---|
value |
string | Get/set selected time |
label |
string | Get/set the input label |
disabled |
boolean | Get/set disabled state |
required |
boolean | Get/set required state |
hour12 |
boolean | Get/set 12-hour format |
locale |
string | Get/set locale formatting |
Events
| Event | Detail | Description |
|---|---|---|
ds-time-picker:change |
{ value, hour, minute, period } |
Fired when time selection changes |
ds-time-picker:open |
— | Fired when the clock opens |
ds-time-picker:close |
— | Fired when the clock closes |
Methods
| Method | Parameters | Description |
|---|---|---|
openClock() |
none | Opens the clock dropdown |
closeClock() |
none | Closes the clock dropdown |
selectHour(hour) |
hour: number | Selects a specific hour |
selectMinute(minute) |
minute: number | Selects a specific minute |
togglePeriod() |
none | Toggles AM/PM (12-hour only) |
CSS Parts
| Part | Description |
|---|---|
input |
Input field element |
clock |
Clock dropdown container |
CSS Custom Properties
| Property | Description |
|---|---|
--ds-time-picker-width |
Width of the input |
--ds-time-picker-input-padding-y |
Input vertical padding |
--ds-time-picker-input-padding-x |
Input horizontal padding |
--ds-time-picker-input-icon-padding |
Right padding for icon |
--ds-time-picker-label-offset-x |
Label left offset |
--ds-time-picker-label-padding-x |
Label horizontal padding |
--ds-time-picker-label-bg |
Label background color |
--ds-time-picker-icon-offset-x |
Icon right offset |
--ds-time-picker-icon-size |
Clock icon size |
--ds-time-picker-clock-padding |
Clock padding |
--ds-time-picker-clock-width |
Clock min width |
--ds-time-picker-clock-header-gap |
Clock header spacing |
--ds-time-picker-mode-gap |
Hour/minute gap |
--ds-time-picker-period-gap |
AM/PM button gap |
--ds-time-picker-period-padding-y |
AM/PM vertical padding |
--ds-time-picker-period-padding-x |
AM/PM horizontal padding |
--ds-time-picker-clock-face-size |
Clock face size |
--ds-time-picker-number-size |
Clock number size |
--ds-time-picker-number-font-size |
Clock number font size |
Accessibility
- ✅ Escape key closes the clock
- ✅ Clock uses dialog role
- ✅ Hour and minute buttons have aria-labels
- ✅ Disabled state prevents interaction
Usage Guidelines
When to Use
- For scheduling and appointment times
- When users need precise time selection
- For alarms, reminders, and timers
Best Practices
- Use 12-hour format for consumer contexts
- Use 24-hour format for global or professional apps
- Label the time context clearly