Time Picker

A time field includes a text input to type a time and a timepicker to select a time.

1<template>
2    <lightning-input type="time" label="Time"> </lightning-input>
3</template>

lightning-input implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

On mobile devices, this component uses the native timepicker, which ignores the time-style attribute. The native timepicker uses the user’s device settings for the input time format.

On desktop, this component uses a timepicker styled with the Lightning Design System. This picker uses the user’s Salesforce locale setting for the time format, either 12-hr time with AM/PM or 24-hr time format. The entered date and time are validated against the user’s Salesforce locale format during the blur event.

The component uses the attribute time-style="short" by default, so the timepicker displays time without seconds. To display time including seconds, set time-style="medium".

Use the value attribute to optionally supply an initial time as an ISO8601 formatted time string such as 14:00:00.000.

Set min and max to ISO8601 formatted time strings to constrain the allowed time value. The time picker displays time values that are within the range only. If you type a time that’s outside the range, the blur event triggers the field to display a validation error message.

To provide a hint for entering information in the field, specify help text with the field-level-help attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

Adding a placeholder value shows the placeholder text in both the date and time fields.

1<template>
2    <lightning-input
3        type="time"
4        label="Event Time"
5        field-level-help="The event time must be between 9AM and 9PM"
6    >
7    </lightning-input>
8</template>

To ensure a time is provided, use the required attribute. Use min and max attributes to constrain the allowed time range. The component automatically validates the time format based on the user’s Salesforce locale.

1<template>
2  <lightning-input
3    type="time"
4    label="Appointment Time"
5    required
6    min="09:00:00.000"
7    max="17:00:00.000"
8    lwc:ref="appointmentTime"
9    message-when-value-missing="Appointment time is required"
10    message-when-range-underflow="Appointment must be after 9:00 AM"
11    message-when-range-overflow="Appointment must be before 5:00 PM"
12  >
13  </lightning-input>
14</template>

An error icon is displayed on an invalid time field, except on desktop browsers.

To validate the time input, use the checkValidity() method. If the value isn’t valid, the reportValidity() method shows the error message below the time field.

1import { LightningElement } from "lwc";
2
3export default class TimeValidation extends LightningElement {
4  handleSubmit() {
5    const timeInput = this.refs.appointmentTime;
6    console.log(timeInput.validity.valid); // Returns true or false
7    if (!timeInput.checkValidity()) {
8      timeInput.reportValidity();
9      return;
10    }
11    // Proceed with form submission
12    const selectedTime = timeInput.value;
13  }
14}

The validity attribute returns an object with read-only boolean properties. For the time type, these attributes apply:

• badInput - Indicates that the value is invalid or doesn’t match the allowed format for the user’s locale
• customError - Indicates that a custom error has been set using setCustomValidity()
• patternMismatch - Indicates that the value doesn’t match the allowed pattern
• rangeOverflow - Indicates that the time is greater than the specified max attribute
• rangeUnderflow - Indicates that the time is less than the specified min attribute
• typeMismatch - Indicates that an invalid format was entered
• valueMissing - Indicates that no value is provided when the required attribute is set
• valid - True if none of the preceding properties are true

The badInput validity error for date and datetime fields displays a default message that varies by locale. For example, “Your entry does not match the allowed format Dec 31, 2024” is displayed for en-US locale, but a different date format is shown for a different locale.

The valueMissing validity error for date and datetime displays “Complete this field with format [format]” where [format] is the date format that’s determined by the user locale. For example: “Complete this field with format Dec 31, 2024”

By default, the timepicker renders above all modals and the main Salesforce header.

You can guide users with a field-level-help tooltip and a placeholder prompt in the text field, as described in Add Field-Level Help and Placeholder Text.

When you use the label attribute, the component generates a unique ID for the internal <label> and uses a standard for attribute to link it to the time field.

If you use the label-hidden variant, the component maintains the for attribute to link between the time field and the label.

If you use the field-level-help attribute, the component creates an aria-describedby link between the time field and the help tooltip.

If the time field fails validation, the component adds aria-invalid="true" and links the error message to the input by using aria-describedby.

For additional ARIA attributes that you can use, see the lightning-input Specifications tab.

change

The event fired when a value is changed in the input field.

The change event returns one of the following event.target parameters, depending on input type.

The event properties are as follows.

lightning-input

For this component’s attributes and methods, see the lightning-input Specifications tab.