Create

Form

Time Picker

Copy page View as Markdown Open in ChatGPT Open in Claude

A time field with hour, minute, second and AM/PM columns or a list of times: typed or picked, with steps, a time window, unavailable times and confirmation.

Usage#

app.component.ts
import { WdsTimePickerComponent } from '@wds/angular/time-picker';

Examples#

Default#

Type a time (930, 14:30, 14h30, 2:30 pm) or pick it in the columns; ↑/↓ in the field step to the next or previous time and Alt+↓ opens the columns. Each column has a header and five rows with the selection in the middle; Now, Clear and OK are under them. The value is ISO text (14:30), as in <input type="time">, and wds-change sends it in detail.value.

Time

Button trigger#

trigger="button" shows an outline button with the time (or “Select time”) instead of a field to type in; it opens the columns with focus in the hours.

Check-in time

Inline#

inline shows the columns in place, always open, with Now and Clear under them. Digits jump to a value in a column (0, 7 → 07).

Hour cycle#

The clock follows the language (en-US – 12 hours with AM/PM, pl – 24 hours); hour-cycle sets it explicitly. The value is always on the 24-hour clock.

24-hour 12-hour Polish

Full format#

seconds (or granularity="second") adds a seconds column, here every 5 seconds (second-step); with the 12-hour clock there is also an AM/PM column. The value is 19:45:00.

Go live at

Hour only#

granularity="hour" leaves only the hour column; the value is a full hour (08:00). hour-step limits it further (e.g. every 2 hours).

Daily digest Sent once a day at this hour.

Step and range#

minute-step limits the minute column, min and max disable the hours and minutes outside the window. A pick or a typed time outside them moves to the nearest allowed time. min after max is an overnight window (22:00–06:00).

Start time Office hours, every 15 minutes. Night shift 22:00 to 06:00.

Unavailable times#

disabled-times disables single times and ranges with an exclusive end (12:00-13:00 10:30 15:00); for times from an API set isTimeDisabled, a function that gets the time as ISO text. An unavailable value makes the field invalid (customError).

Appointment Lunch 12:00–13:00; 10:30 and 15:00 are booked.

Confirm with OK#

require-confirm keeps a pick (also Now and Clear) as a draft until OK or Enter; Escape, a click outside or closing discards it and the value stays.

Publish at

Actions#

actions chooses the buttons under the columns from now, clear and ok (here without Now, because the time is in another time zone); actions="" hides the row.

Doors open Venue time (Europe/Lisbon, WEST).

Localization#

The language (locale or the nearest lang) sets AM/PM and its position (下午 2:30 in Chinese), the column headers and “Now”. The columns stay left to right in right-to-left text. The field also reads Arabic-Indic and full-width digits.

Deutsch 中文 العربية

List#

variant="list" opens one list of times instead of the columns, like a select: every minute-step minutes (every 15 when the step is 1), between min and max. ↑/↓ move through the list while focus stays in the field, Enter picks. With relative-to (the start of an event) the list starts after that time and shows the length of each option, as in calendar apps.

Start End

Clearable#

clearable adds a clear button to the field when a time is selected.

Reminder

Mobile panel#

On screens narrower than 640 px (panel="auto") the columns open in a panel at the bottom of the screen, with larger options; focus goes straight to the columns, so the on-screen keyboard stays hidden. panel="sheet" always opens the panel, panel="popup" never.

Pickup time

Disabled, read-only and invalid#

disabled blocks the field, readonly keeps it focusable but without typing and columns, invalid on wds-field shows the error state.

Disabled Read-only Invalid Select a time.

Forms#

Integration with Angular forms. Pick the API your app uses.

Signal forms#

WdsDatePickerField also connects wds-time-picker to [formField] (a string, e.g. 14:30).

Start timeSubmit

Submitted: —

Template-driven#

WdsDatePickerValueAccessor makes ngModel work on wds-time-picker.

Start timeSubmit

Submitted: —

Reactive forms#

The same WdsDatePickerValueAccessor works with formControl and formControlName.

Start timeSubmit

Submitted: —

API References#

wds-time-picker#

A time field with hour and minute columns in a popup. The time can be typed (14:30, 1430, 14h30, 2:30 pm) or picked in the columns. The value is ISO text (14:30, with seconds 14:30:15), as in <input type="time">. On phones the columns open in a panel at the bottom of the screen (panel). Each column has a header and shows five rows (--wds-time-picker-rows); the selected row stays in the middle. Under the columns are Now, Clear and OK (actions). granularity sets the columns (hour, minute, second), hour-step, minute-step and second-step the values in them, min/max the window (min after max is an overnight window, 22:00–06:00) and disabled-times or isTimeDisabled the unavailable times. A pick that is not allowed moves to the nearest allowed time; so does a typed time. trigger="button" shows an outline button instead of a field to type in, inline shows the columns in place (always open), and require-confirm keeps a pick as a draft until OK (Escape or closing discards it). A form control: name submits the time; required, min, max, the steps and the unavailable times validate as in a native field, and text that is not a valid time gives badInput. With variant="list" the popup is one list of times, like a select: every minute-step minutes (every 15 when the step is 1), from min to max. With relative-to (such as the start of an event) the list starts after that time and shows the length of each option, as in calendar apps. Keyboard: ↑/↓ in the field step to the next or previous allowed time, Alt+↓ opens the columns. In a column ↑/↓ change the value, digits jump to it (1, 4 → 14), ←/→ move between columns, Enter (or Alt+↑) confirms and Escape closes, both returning to the field. In the list variant ↓ opens the list and ↑/↓ move through it (focus stays in the field), Home/End go to the first or last time, Enter picks and Escape closes.

Attributes

AttributeTypeDefaultDescription
valuestring''The selected time (14:30 or 14:30:15).
minstring''The earliest allowed time (08:00). After max the window runs overnight (22:00 to 06:00).
maxstring''The latest allowed time (18:00).
granularityWdsTimeGranularity'minute'The finest column and the precision of the value: hour (14:00), minute or second (14:30:15).
hour-step.hourStepnumber1Hours between the options of the hour column (e.g. 2: 00, 02, 04…).
minute-step.minuteStepnumber1Minutes between the options of the minute column (e.g. 15: 00, 15, 30, 45).
second-step.secondStepnumber1Seconds between the options of the seconds column.
disabled-times.disabledTimesstring''Unavailable times: single times and ranges with an exclusive end, e.g. 12:00-13:00 15:30.
require-confirm.requireConfirmbooleanfalseA pick (also Now and Clear) stays a draft until OK or Enter; Escape and closing discard it.
actionsstring'now clear ok'Buttons under the columns, from now, clear and ok (OK only in the popup or with require-confirm); empty hides the row.
variantWdsTimePickerVariant'columns'columns: hour and minute columns; list: one list of times, like a select.
triggerWdsTimePickerTrigger'input'input: a field to type in; button: an outline button with the time that opens the columns.
inlinebooleanfalseShows the columns and the actions in place, always open, without a field.
relative-to.relativeTostring''list: the list starts after this time (09:00) and each option shows its length from it, such as for the end of an event.
secondsbooleanfalseAdds a seconds column (value 14:30:15); the same as granularity="second".
hour-cycle.hourCycle12 | 24 | undefined12 or 24-hour clock. Defaults to the language (en-US → 12).
panelWdsPickerPanel'auto'Where the columns open: auto (a popup, on phones a panel at the bottom), popup or sheet.
localestring''Language (e.g. en-US): AM/PM, its position, the column headers and Now. Defaults to the nearest lang attribute.
placeholderstring''Placeholder of the empty field. Defaults to the format, e.g. hh:mm (with trigger="button" Select time).
namestring''Field name in a form.
requiredbooleanfalseA time is required (valueMissing when empty).
disabledbooleanfalseDisables the field.
readonlybooleanfalseRead-only: no typing and no columns.
invalidbooleanfalseError state (e.g. from the app's validation).
clearablebooleanfalseA clear button in the field when a time is selected (trigger="input").
openbooleanfalseWhether the columns are open.

Properties

PropertyDescription
isTimeDisabled((value: string) => boolean) | nullCustom rule for unavailable times (e.g. booked slots). Gets the time as ISO text in the granularity.

Events

EventDescription
wds-changeCustomEvent<WdsTimePickerChangeDetail>The user changes the time (columns, typing, Now, Clear, OK).
wds-open-changeCustomEvent<WdsTimePickerOpenChangeDetail>The user opens or closes the columns.

Methods

MethodDescription
show()Opens the columns.
close()Closes the columns.
focus(options?: FocusOptions)
formResetCallback()
formDisabledCallback(disabled: boolean)
checkValidity()Returns true when the value is valid; otherwise fires invalid on the element.
reportValidity()Like checkValidity(), and shows the browser validation bubble when the value is invalid.
setCustomValidity(message: string)Sets a custom validation error (an empty string clears it), like input.setCustomValidity().

CSS parts (::part)

PartDescription
fieldThe field border (with trigger="button" the button).
inputThe native <input>.
clearThe clear button in the field.
triggerThe button with the clock icon (with trigger="button" the whole button).
popupThe popup (on phones the panel).
panelThe columns and the actions shown in place (inline).
timeThe row of columns.
time-columnA column with its header.
time-labelThe header of a column.
time-optionA single hour, minute, second or AM/PM.
footerThe row of actions.
actionA button in the footer; also action-now, action-clear, action-ok.
listThe list of times (list).
list-optionA time in the list (list).

CSS custom properties

PropertyDescription
--wds-time-picker-widthWidth of the field.
--wds-time-picker-rowsRows visible in a column (default 5; keep it odd).
--wds-time-picker-fade-sizeDepth of the fade at a column end with hidden rows (default one row).
--wds-time-picker-heightHeight of the list (list, default 16rem).

Accessibility#

Screen reader#

The text field has role="combobox" with aria-haspopup="dialog" and aria-expanded; the format (e.g. hh:mm) is its description. Give it a name with wds-field-label or aria-label (fallback: Time). With trigger="button" it is a button named by the label and the time.

The columns open in a popup with role="dialog". Each column is a listbox named by its header (“Hour”, “Minute”, “Second”, “AM/PM”, in the language of the page) and described by the whole time; its active option is announced with aria-activedescendant, and options outside min/max or unavailable have aria-disabled. inline columns are in a group.

With variant="list" the field has aria-haspopup="listbox" and the popup is a listbox of options; the highlighted time is announced with aria-activedescendant and the chosen one has aria-selected.

invalid, required and a typed text that is not a time set aria-invalid / aria-required. In a form the time is submitted under name.

Keyboard support#

KeyFunction
ArrowUpArrowDownIn the field: the next or previous allowed time.
Alt + ArrowDownIn the field: opens the columns with focus on the hours.
EnterIn the field: accepts the typed time. In a column: confirms (also a draft with require-confirm) and returns to the field.
ArrowUpArrowDownIn a column: the previous or next allowed value (selection follows focus, it wraps around).
09APIn a column: jump to a value (digits; two within a second are one number) or to AM/PM.
PageUpPageDownHomeEndIn a column: 5 values back or forward, the first or the last value.
ArrowLeftArrowRightMove between the columns.
TabMoves through the columns and the buttons; in the popup it cycles.
Alt + ArrowUpIn a column: confirms and closes, like Enter.
EscapeCloses the columns and returns focus to the field; with require-confirm the draft is discarded.
ArrowUpArrowDownHomeEndWith variant="list": ↓ opens the list; in the open list the previous or next time, the first or the last (focus stays in the field).
Footer