Time Picker
- Usage
- Styling
Time Picker is an input field for used entering or selecting a specific time.
The time can be entered directly using a keyboard, or by choosing a value from a set of predefined options presented in an overlay. The overlay opens when the field is clicked — or when any input is entered while the field is focused.
Step
Time Picker’s step parameter defines the interval in seconds between the items displayed in the overlay. It also specifies the amount by which the time increases or decreases using the Up and Down arrow keys — when the overlay is disabled.
The default step is one hour (i.e., 3600
seconds). Unlike Number Field, Time Picker accepts values that don’t align with the specified step.
Note
|
Use Common Steps
A step must evenly divide an hour or day. For example, "15 minutes" and "30 minutes" are valid steps for an hour, and "2 hours" is a valid step for a day, whereas "42 minutes" isn’t valid for either.
|
The displayed time format changes based on the step.
Step | Format |
---|---|
Less than 60 seconds. | HH:MM:SS |
Less than 1 second. | HH:MM:SS:FFF |
Note
|
Limit Number of Steps
The overlay doesn’t appear for steps less than 900 seconds (i.e., 15 minutes), to avoid showing an impractical number of choices.
|
Auto Open
The overlay opens automatically when the field is focused using a pointer (i.e., a mouse or touch), or when the user types in the field. You can disable this so that the overlay opens only when the toggle button — or the Up or Down arrow keys — is pressed.
Validation
Minimum & Maximum Value
You can define a minimum and maximum value for Time Picker if you need to restrict the input to a specific range:
new tab
<TimePicker
label="Appointment time"
helper-text="Open 8:00-16:00"
value={currentValue}
min="08:00"
max="16:00"
step={60 * 30}
errorMessage={errorMessage}
onValueChanged={(event) => {
setCurrentValue(event.detail.value);
}}
onChange={(event: TimePickerChangeEvent) => {
const { min, max, value } = event.target;
if (value < min) {
setErrorMessage('Too early, choose another time');
} else if (value > max) {
setErrorMessage('Too late, choose another time');
} else {
setErrorMessage('');
}
}}
/>
Basic Features
The following features, common to most input field components, are supported:
Label
The label is used to identify the input field. It supports plain-text content, and its length is limited to the width of the field. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.
Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby
attribute. Fields without any visible label should include an invisible label for assistive technologies with the aria-label
attribute.
Helper
Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.
A style variant is available for rendering the helper above the field.
In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.
Placeholder
The placeholder is text that’s displayed when the field is empty. Its primary purpose is to provide a short input hint (e.g., the expected format) in situations where a Helper cannot be used.
Placeholders should not be used as a replacement for a visible label. They can be mistaken for a manually entered value. See Label for alternatives to the built-in field label.
Tooltip
Tooltips are small text pop-ups displayed on hover, and on keyboard-focus. They can be used to provide additional information about a field. This can be useful in situations where an always visible Helper is not appropriate. Helpers are generally recommended in favor of tooltips, though, as they provide much better discoverability and mobile support. See the Tooltip documentation for more information.
Prefix
A prefix element — rendered at the start of the field — can be used to display units, icons, and similar visual cues to the field’s purpose or format.
External & Invisible Labels (ARIA)
Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id
. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.
<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-time-picker accessible-name-ref="external-label">...
<!-- Invisible label for screen readers: -->
<vaadin-time-picker accessible-name="This is the label">...
new tab
<TimePicker label="Label" helperText="Helper text" placeholder="Placeholder" clearButtonVisible>
<Tooltip slot="tooltip" text="Tooltip text" />
<Icon slot="prefix" icon="vaadin:vaadin-h" />
</TimePicker>
Read-Only & Disabled
Fields used to display values should be set to read-only
mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.
Fields that are currently unavailable should be disabled
. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.
Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.
new tab
<HorizontalLayout theme="spacing">
<TimePicker readonly label="Read-only" value="07:00" />
<TimePicker disabled label="Disabled" />
</HorizontalLayout>
Style Variants
The following style variants can be applied:
Text Alignment
Three different text alignments are supported: left
, which is the default; center
; and right
.
Right-alignment is recommended for numerical values when presented in vertical groups. This tends to aid interpretation and comparison of values.
Small Variant
The small variant can be used to make individual fields more compact. The default size of fields can be customized with <<https://vaadin.com/docs/styling/lumo/lumo-style-properties#,style properties>>.
Helper Above Field
The helper can be rendered above the field, and below the label.
Borders
Borders can be applied to the field surface by providing a value (e.g., 1px
) to the --vaadin-input-field-border-width
CSS property. This can be applied globally to all input fields using the html
selector, or to individual component instances. Borders are required to achieve WCAG 2.1 level AA conformant color contrast with the default Lumo styling of fields.
You can override the default border color with the --vaadin-input-field-border-color
property.
new tab
<TimePicker
theme="align-right small helper-above-field"
label="Label"
helperText="Helper text"
value="07:00"
style={{ '--vaadin-input-field-border-width': '1px' } as React.CSSProperties}
/>
Best Practices
Use Time Picker when the user needs to choose a time of day. Don’t use it for durations, such as for a stopwatch or timer.
Related Components
Component | Usage Recommendation |
---|---|
Input field for entering or selecting a specific date. | |
Input field for entering or selecting a specific date and time. |