Time picker
A time picker is a form field for a time of day. People type any time or pick a suggestion; the form gets a 24-hour time such as 19:30.
<tk-field label="Start time" helper="For example, 2:30 PM"> <tk-time-picker name="start" interval="15" min="09:00" max="17:00"></tk-time-picker> </tk-field>
Put the time picker in a aria-label. Inside a Field, set required and disabled on the
Field.
Anatomy
| Part | What it is |
|---|---|
tk-time-picker |
the element; one Tab stop |
field part |
the bordered box; fills its container |
input part |
the native text input; always typable |
| clock icon | at the end of the box; decoration, not a button |
listbox part |
the suggestion list; as wide as the box; opens below it, or above near the bottom of the screen |
The list only suggests. People can type 7:37 PM even when the list steps by 30 minutes.
Sizes
<tk-time-picker aria-label="Pickup time" value="09:30"></tk-time-picker> <tk-time-picker size="large" aria-label="Return time" value="17:00"></tk-time-picker>
size |
Height | Padding-inline | Value text | Suggestion row |
|---|---|---|---|---|
medium (default) |
32px | space-8 |
Body Small (14/20) | 32px |
large |
36px | space-10 |
Body Medium (16/24) | 36px |
The heights match Input and Button.
States
<tk-time-picker aria-label="Opens at" value="08:00" readonly></tk-time-picker> <tk-time-picker aria-label="Closes at" value="18:00" disabled></tk-time-picker>
<tk-field label="Reminder time" error="Enter a real time"> <tk-time-picker name="reminder"></tk-time-picker> </tk-field>
The box doesn't change on hover. On focus, its border takes the focus color and grows thicker inward; it stays that way while the list is open.
readonly: people can focus and copy the time; the list doesn't open.disabled: nothing works, and the time is left out of the form.- Error: set
erroron the Field. The border turns red and the message shows under the box.
Typing a time
The text is read when people press Enter or leave the field. Case doesn't matter, and "p.m." works too.
21:30,9:30, or14.009or21: a whole hour930,0930, or1730- any of these with AM or PM:
9:30pm,9 PM,930p
Without AM or PM, the time reads as 24-hour: 9:30 is morning. With AM or PM, hours go
from 1 to 12; 12 AM is midnight. Words such as "noon" don't work.
After a time is read, the field shows it as "9:30 AM", or "09:30" with
hour-cycle="h23". If the text isn't a real time, the field keeps it, clears the value,
and blocks the form from submitting.
Suggestions
<tk-time-picker aria-label="Quiet hours start" hour-cycle="h23" interval="60" min="22:00" max="07:00"></tk-time-picker>
intervalsets the step between suggestions in minutes: 30 by default, 15 for scheduling. It must divide 60. It never rejects a typed time.minandmaxlimit the list and the value. Whenminis later thanmax, the window crosses midnight:22:00to07:00lists 22:00 through 07:00.- A click in the field, or
Down, opens the list. Typing never opens or filters it. - The list opens at the chosen time, or at the next suggestion after now. A check marks the chosen time.
- Focus stays in the field. Moving through the list doesn't change the value; Enter, a click, or Tab on a highlighted row does.
Escor a click outside closes the list without picking.
When to use
- Use a time picker when people choose the time: a meeting start, a reminder.
- Use a
Select when your product decides which times exist, such as appointment slots or delivery windows. - Use a
Number input with a unit for a duration, such as 90 minutes. - For a date and time, put a
Date picker and a time picker side by side. Don't merge them into one field. - For a time range, use two time pickers joined by "to".
- For a time zone, use a separate
Select , or name it in text: "9:00 AM PST".
Content
- Name the time's role in the label: "Start time", "Pickup time", not "Time".
- Put the format in the helper with an example: "For example, 2:30 PM". Not in the placeholder.
- Write AM and PM in capitals, without periods: "2:30 PM".
- Pick the first error that applies:
| Problem | Error message |
|---|---|
| empty and required | "Enter a start time" |
| not a real time | "Enter a real time" |
outside min / max |
"Start time must be between 9:00 AM and 5:00 PM" |
Rules across fields, such as an end after the start, are yours to check. More in
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Label the time's role: "Start time" | Label it "Time" |
| Put "For example, 2:30 PM" in the helper | Put the format only in the placeholder |
Set interval to what the task needs |
List every minute of the day |
| Put a date picker and a time picker side by side | Merge date and time into one field |
| Use a select for slots your product sets | Use a time picker for fixed slots |
| Use a number input with a unit for a duration | Use a time picker for "how long" |
Related
Field : the label, helper, and error around a time picker.Date picker : the date next to the time.Select : fixed time slots and time zones.Combobox : a list that filters as people type; this one doesn't.Input : the box this field shares.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
value |
24-hour HH:mm |
'' |
the time; submits under name in this form, whatever the display |
name |
string | — | the form field name |
hour-cycle |
h12 | h23 |
h12 |
shows "9:30 AM" or "09:30" |
interval |
minutes | 30 |
the step between suggestions; must divide 60 |
min / max |
HH:mm |
— | the allowed times; min after max crosses midnight |
required |
boolean | false |
an empty field blocks submission; no visible mark (the Field adds the asterisk) |
readonly |
boolean | false |
focusable and copyable; the list doesn't open |
disabled |
boolean | false |
not focusable, left out of the form |
placeholder |
string | — | text shown while empty; avoid it |
size |
medium | large |
medium |
height 32 / 36px |
Events
change fires when the time changes: after typing a time that reads, or after picking a
suggestion. input fires on every keystroke. Setting value in code fires nothing.
Resetting the form restores the first value.
CSS
::part(field): the bordered box.::part(input): the native text input.::part(listbox): the suggestion list.
Tokens
The box uses the
| Part | Tokens |
|---|---|
| clock icon | icon/secondary, icon-size-16; disabled icon/disabled |
| list | surface/raised + shadow-2, radius-16, space-4 padding |
| suggestion row | text/default, Label Medium (14/20), radius-12; highlighted state/hover |
| chosen row | the check, icon/accent |
In high contrast, the list also gets a 1px border/default. Values per theme:
Accessibility
Built in:
- A native text input that announces as a combobox with a list, open or closed, and the highlighted suggestion.
- One Tab stop: the clock icon is decoration, and focus stays in the field.
- The value always submits as 24-hour time, whatever the display.
- A time that can't be read, a missing required time, or a time out of bounds blocks submission and moves focus to the field.
- Every row is at least 32px tall.
Your part:
- Name every time picker: a Field label with the time's role, or
aria-label. - Put the format example in the helper.
- Set
interval,min, andmaxto fit the task. - Name the time zone in text when it matters.
| Key | List closed | List open |
|---|---|---|
Down / Up / Alt + Down |
opens the list at the chosen or nearest time | moves the highlight; stops at the ends |
Enter |
reads the typed time, then submits the form | picks the highlighted row, or reads the typed time; closes |
Esc |
— | closes the list |
Tab |
moves on | picks the highlighted row, then moves on |
Home / End / Left / Right |
move the text cursor | move the text cursor |
Contrast limits
- Field border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. Always show a label.