TimePicker
Description
<vaadin-time-picker>
is a Web Component providing a time-selection field.
<vaadin-time-picker></vaadin-time-picker>
timePicker.value = '14:30';
When the selected value
is changed, a value-changed
event is triggered.
Styling
The following custom properties are available for styling:
Custom property | Description | Default |
---|---|---|
--vaadin-field-default-width |
Default width of the field | 12em |
--vaadin-time-picker-overlay-width |
Width of the overlay | auto |
--vaadin-time-picker-overlay-max-height |
Max height of the overlay | 65vh |
The following shadow DOM parts are available for styling:
Part name | Description |
---|---|
label |
The label element |
input-field |
The element that wraps prefix, value and buttons |
clear-button |
The clear button |
error-message |
The error message element |
helper-text |
The helper text element wrapper |
required-indicator |
The required state indicator element |
toggle-button |
The toggle button |
overlay |
The overlay container |
content |
The overlay content |
The following state attributes are available for styling:
Attribute | Description |
---|---|
disabled |
Set when the element is disabled |
has-value |
Set when the element has a value |
has-label |
Set when the element has a label |
has-helper |
Set when the element has helper text or slot |
has-error-message |
Set when the element has an error message |
has-tooltip |
Set when the element has a slotted tooltip |
invalid |
Set when the element is invalid |
focused |
Set when the element is focused |
focus-ring |
Set when the element is keyboard focused |
readonly |
Set when the element is readonly |
opened |
Set when the overlay is opened |
Internal components
In addition to <vaadin-time-picker>
itself, the following internal
components are themable:
<vaadin-time-picker-item>
- has the same API as<vaadin-item>
.
See Styling Components documentation.
Change events
Depending on the nature of the value change that the user attempts to commit e.g. by pressing Enter,
the component can fire either a change
event or an unparsable-change
event:
Value change | Event |
---|---|
empty => parsable | change |
empty => unparsable | unparsable-change |
parsable => empty | change |
parsable => parsable | change |
parsable => unparsable | change |
unparsable => empty | unparsable-change |
unparsable => parsable | change |
unparsable => unparsable | unparsable-change |
Properties
accessibleName
Type: string | null | undefined
String used to label the component to screen reader users.
accessibleNameRef
Type: string | null | undefined
Id of the element used as label of the component to screen reader users.
allowedCharPattern
Type: string
A pattern matched against individual characters the user inputs.
When set, the field will prevent:
keydown
events if the entered key doesn't match/^allowedCharPattern$/
paste
events if the pasted text doesn't match/^allowedCharPattern*$/
drop
events if the dropped text doesn't match/^allowedCharPattern*$/
For example, to allow entering only numbers and minus signs, use:
allowedCharPattern = "[\\d-]"
autofocus
Type: boolean
Specify that this control should have input focus when the page loads.
autoOpenDisabled
Type: boolean | null | undefined
Set true to prevent the overlay from opening automatically.
autoselect
Type: boolean
If true, the input text gets fully selected when the field is focused using click or touch / tap.
clearButtonVisible
Type: boolean
Set to true to display the clear icon which clears the input.
It is up to the component to choose where to place the clear icon:
in the Shadow DOM or in the light DOM. In any way, a reference to
the clear icon element should be provided via the clearElement
getter.
disabled
Type: boolean
If true, the user cannot interact with this element.
errorMessage
Type: string | null | undefined
Error to show when the field is invalid.
helperText
Type: string | null | undefined
String used for the helper text.
i18n
Type: TimePickerI18n
The object used to localize this component. To change the default localization, replace this with an object that provides both the time parsing and formatting functions.
The object has the following JSON structure:
{
// A function to format given `Object` as
// time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
formatTime: (time) => {
// returns a string representation of the given
// object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats
},
// A function to parse the given text to an `Object` in the format
// `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.
// Must properly parse (at least) text
// formatted by `formatTime`.
parseTime: text => {
// Parses a string in object/string that can be formatted by`formatTime`.
}
}
NOTE: formatTime
and parseTime
must be implemented in a
compatible manner to ensure the component works properly.
See also: TimePickerI18n
invalid
Type: boolean
Set to true when the field is invalid.
label
Type: string | null | undefined
The label text for the input node. When no light dom defined via [slot=label], this value will be used.
manualValidation
Type: boolean
Set to true to enable manual validation mode. This mode disables automatic
constraint validation, allowing you to control the validation process yourself.
You can still trigger constraint validation manually with the validate()
method
or use checkValidity()
to assess the component's validity without affecting
the invalid state. In manual validation mode, you can also manipulate
the invalid
property directly through your application logic without conflicts
with the component's internal validation.
max
Type: string
Maximum time allowed.
Supported time formats are in ISO 8601:
hh:mm
hh:mm:ss
hh:mm:ss.fff
min
Type: string
Minimum time allowed.
Supported time formats are in ISO 8601:
hh:mm
hh:mm:ss
hh:mm:ss.fff
name
Type: string
The name of this field.
opened
Type: boolean
True if the dropdown is open, false otherwise.
pattern
Type: string
A regular expression that the value is checked against. The pattern must match the entire value, not just some subset.
placeholder
Type: string
A hint to the user of what can be entered in the field.
readonly
Type: boolean
When present, it specifies that the field is read-only.
required
Type: boolean
Specifies that the user must fill in a value.
step
Type: number | null | undefined
Defines the time interval (in seconds) between the items displayed
in the time selection box. The default is 1 hour (i.e. 3600
).
It also configures the precision of the value string. By default
the component formats values as hh:mm
but setting a step value
lower than one minute or one second, format resolution changes to
hh:mm:ss
and hh:mm:ss.fff
respectively.
Unit must be set in seconds, and for correctly configuring intervals in the dropdown, it need to evenly divide a day.
Note: it is possible to define step that is dividing an hour in inexact fragments (i.e. 5760 seconds which equals 1 hour 36 minutes), but it is not recommended to use it for better UX experience.
title
Type: string
The text usually displayed in a tooltip popup when the mouse is over the field.
value
Type: string
The time value for this element.
Supported time formats are in ISO 8601:
hh:mm
(default)hh:mm:ss
hh:mm:ss.fff
Methods
checkValidity
Type: (() => boolean) & (() => boolean)
Returns true if the current input value satisfies all constraints (if any). You can override this method for custom validations.
clear
Type: () => void
Clear the value of the field.
close
Type: () => void
Closes the dropdown list.
open
Type: () => void
Opens the dropdown list.
validate
Type: () => boolean
Validates the field and sets the invalid
property based on the result.
The method fires a validated
event with the result of the validation.
Events
change
Type: TimePickerChangeEvent
Fired when the user commits a value change.
input
Type: CustomEvent
Fired when the value is changed by the user: on every typing keystroke, and the value is cleared using the clear button.
invalid-changed
Type: TimePickerInvalidChangedEvent
Fired when the invalid
property changes.
opened-changed
Type: TimePickerOpenedChangedEvent
Fired when the opened
property changes.
validated
Type: TimePickerValidatedEvent
Fired whenever the field is validated.
value-changed
Type: TimePickerValueChangedEvent
Fired when the value
property changes.
Types
TimePickerChangeEvent
/**
* Fired when the user commits a value change.
*/
export type TimePickerChangeEvent = Event & {
target: TimePicker;
};
TimePickerI18n
export interface TimePickerI18n {
parseTime?(time: string): TimePickerTime | undefined;
formatTime?(time: TimePickerTime | undefined): string;
}
TimePickerInvalidChangedEvent
/**
* Fired when the `invalid` property changes.
*/
export type TimePickerInvalidChangedEvent = CustomEvent<{ value: boolean }>;
TimePickerOpenedChangedEvent
/**
* Fired when the `opened` property changes.
*/
export type TimePickerOpenedChangedEvent = CustomEvent<{ value: boolean }>;
TimePickerTime
/**
* @license
* Copyright (c) 2018 - 2025 Vaadin Ltd.
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
*/
export interface TimePickerTime {
hours: number | string;
minutes: number | string;
seconds?: number | string;
milliseconds?: number | string;
}
TimePickerValidatedEvent
/**
* Fired whenever the field is validated.
*/
export type TimePickerValidatedEvent = CustomEvent<{ valid: boolean }>;
TimePickerValueChangedEvent
/**
* Fired when the `value` property changes.
*/
export type TimePickerValueChangedEvent = CustomEvent<{ value: string }>;