Time field

The Time Field allows users to enter a time (HH:MM) by typing or using a dropdown with split hour and minute columns. It supports configurable hour/minute steps with free typing by default, plus an optional strict mode that enforces steps that require matching a stepped option. The control favours predictability (no reordering or injected suggestions), solid keyboard flow, and clear validation.

Usage

Code

Accessibility

  <sl-time-field aria-label="Lesson start time"></sl-time-field>

When to use

The following guidance describes when to use the time field component.

Precise input and fast selection

Use the Time Field when the task requires an exact clock time and you want to accelerate entry with predictable stepped options. The split-column dropdown provides quick, scannable choices for common schedules (e.g., every 5/10/15/30 minutes) while still allowing direct typing. This is ideal for meetings, bookings, reminders, and any workflow where consistent, granular time values matter.

Use the Time Field when forms must support speed and accessibility for keyboard-centric users. The input accepts typed values, opens the dropdown via keyboard, and allows navigation of hour/minute columns with the arrow keys. This is especially useful in dense forms, operational tooling, or power-user interfaces where mouse interaction is secondary.

When not to use

Time fields may not be the best choice in the following scenarios:

Relative timeframes

Avoid the Time Field when only approximate periods or relative notions of time are needed (e.g., "morning," "after lunch," "end of day"). Similarly, do not use it for durations (e.g., selecting "01:30" to indicate 90 minutes). In these cases, it might be better to use radio buttons, a segmented control, or a select that reflects a certain duration rather than a timestamp.

Anatomy

Item	Name	Description	Optional
1	Container	Wraps input and trigger, provides focus ring and error visuals.	no
2	Input	Editable time field for time entry.	no
3	Placeholder	Hint text when no value is set (e.g., “HH:MM”).	no
4	Icon Button	Opens the dropdown.	no

States

Idle: Empty, showing the placeholder, or with a formatted time as the value.
Hover: Visual hover effects that show the user that the field is interactive.
Focus: Display the focus ring. It's shown when the field is active by clicking or keyboard navigation.
Invalid: When an incorrect value is entered, the field is styled to indicate the error.
Disabled: Non-interactive, muted.

Figma Options

With these options you can tweak the appearance of the time field in Figma. They are available in the Design Panel so you can compose the time field to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Open	`on` or `off`	Opens a dropdown with hours and minutes options for time selection.
Variant	`default` `valid` `invalid`	When you're working on a scenario where you show what happens when a field is skipped or filled in incorrectly you can choose a different variant to show this.
Size	`md` `lg`	The time field is available in two sizes. If not specified the default value is `md` (medium).
Placeholder	`on` or `off`	If the setting is enabled, the placeholder will be visible, whereas if it is disabled, the user's input will be displayed. Default value is `off`.
Text	`value`	Use placeholder text to give the user a short hint about what they need to input (e.g. a sample value or a short description of the expected format). Placeholder is not a replacement for labels. It's an optional feature that disappears once users begin entering their data.
Placeholder text	`value`	Use placeholder text to show the expected time format (e.g., "HH:MM" or "14:30"). The placeholder disappears once users begin typing. It should not replace the label but serve as a format hint.
Label	`value`	Provide users with a clear, concise label that describes the time being requested (e.g., "Start time", "Appointment time", "Exam time").

Behavior

Free Typing (Default)

Users can type any valid HH:MM time, regardless of whether it is a step time. The component validates for format and parsability (e.g., two-digit hours/minutes within valid ranges). Step alignment is not enforced unless enforceSteps = true.

Stepped Options (Shortcuts)

When steps are configured, the dropdown shows stepped options in the hour and/or minute columns (e.g., 00, 15, 30, 45). These options act as shortcuts while typed input remains unrestricted. The dropdown options always display in ascending order and do not dynamically adjust based on the current input value.

Enforced Steps (Optional)

When enforceSteps = true, only stepped values are valid. If a user types an invalid time, a validation message appears after the field is blurred (i.e., when the user leaves the field). The typed value remains visible until corrected. The dropdown content and order still do not change.

Press Tab to focus the field and start typing or press tab again so the focus moves to the clock icon and then press Enter/Space to open the dropdown. Use the Arrow keys to navigate the hour and minute columns. Typing in the input updates the value; in strict mode, off-step values are validated when the field loses focus. Press Esc to close the dropdown and return focus to the input.

Click on the field or dropdown button, or press Enter/Space when the button with the clock icon has focus.

Formatting & Validation

The control accepts and normalises valid times as HH:MM. Optional minTime / maxTime constraints may be applied with clear validation messages. When enforceSteps = true, error text should indicate the required step pattern (e.g., “Select a time in 15-minute steps: 00, 15, 30, 45”).

Text Field: If you want a free-form text input.
Select: Selecting from predefined numeric options.

  <sl-time-field aria-label="A parent‑teacher meeting" value="16:30"></sl-time-field>

Localization

The separator between hours and minutes follows the active locale (via Intl.DateTimeFormat).
Most locales use a colon :, but a few (for example Finnish fi) use a dot . (e.g. 16.30).

Supported format

The time field supports the 24-hour format HH:MM (hours 00–23, minutes 00–59).
This 24-hour notation is the most common in Europe and is the component default.
12-hour AM/PM format is not supported yet.

API

Component to pick and edit a time for many use cases, with accessibility and validation.

Properties

Name	Attribute	Type	Default	Description
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the time field is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`static hourStep`	`hour-step`	`number`	`1`	The default step between each hour option.
`hourStep`	-			The step between each hour option.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`locale`	`locale`	`string`		The component's locale.
`max`	`max`	`string \| undefined`	`undefined`	The maximum time selectable in the field.
`min`	`min`	`string \| undefined`	`undefined`	The minimum time selectable in the field.
`static minuteStep`	`minute-step`	`number`	`5`	The default step between each minute option.
`minuteStep`	-			The step between each minute option.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`placeholder`	`placeholder`	`string \| undefined`	`undefined`	The placeholder for the time field.
`readonly`	`readonly`	`boolean \| undefined`	`false`	Whether the time field is readonly.
`required`	`required`	`boolean \| undefined`	`false`	Whether the time field is a required field.
`showValid`	-	`boolean`	`false`	Optional property to indicate the valid state should be shown.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`start`	`start`	`string \| undefined`	`undefined`	The start time; the time that has the initial focus when the picker is opened without a value. If will use the current time if not explicitly set.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value for this form control.

Methods

Name	Parameters	Return	Description
`renderHours`		`TemplateResult[]`	Renders hour options (00–23) using hourStep, applies min/max constraints, and marks the selected hour with aria-selected. Can be overridden.
`renderMinutes`		`TemplateResult[]`	Renders minute options using minuteStep and marks the selected one with aria-selected. Can be overridden.
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<string>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Keyboard interactions

The time field supports keyboard navigation for both the input and the dropdown time picker.

Command	Description
Tab	When focus is outside the time field, moves focus to the input. If focus is on the input, pressing Tab moves to the dropdown button, then to the next focusable element.
Space/Enter (on button)	Toggles the time picker dropdown when the button has focus.
Escape	Closes the time picker dropdown.
Arrow Up/Down (in dropdown)	Navigates through the hour or minute options in the currently focused column.
Arrow Left/Right (in dropdown)	Switches focus between the hour and minute columns.
Enter (in dropdown)	Selects the currently focused time option and closes the dropdown.

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Attribute	Value	Description
`aria-label`	string	Defines a string that labels the time field. Required when not wrapped with `sl-form-field` and there is no `sl-label` component.
`aria-labelledby`	string	References the ID of the element that labels the time field.
`aria-required`	boolean	Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required. If there is already a `required` attribute added, it is recommended to avoid adding `aria-required`.
`aria-disabled`	boolean	Announces the time field as disabled with a screen reader. See note below about difference from the `disabled` attribute.

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

The disabled attribute dims the time field visually, removes it from tab focus, prevents all interactions, and announces it as disabled.
The aria-disabled attribute only announces the disabled state but doesn't prevent interaction or remove focus.

Use disabled for true disabled states, use aria-disabled only if you need the element to remain in the tab sequence for specific accessibility reasons.

Interactive example