Datetime Picker

lightning-input type="datetime" or type="datetime-local"

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

A datetime field includes a text input to type a date and a datepicker to select a date, and similar fields for typing or picking a time.

There is no behavioral difference between the datetime and datetime-local types.

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.

Input Type	SLDS 1	SLDS 2
datetime	Datetime Picker	Datetime Picker

The timepicker displays a dropdown menu with time options in 15-minute intervals, starting from 12:00 AM. To specify custom time intervals (in minutes) for the dropdown options, use the time-step-minutes attribute. You can pass in an interval of 5 or more minutes.

On mobile devices, this component uses the native datetime picker, which ignores the date-style and time-style attributes. The native datetime picker uses the user's device settings for names of months and weekdays, the input datetime format, and the calendar type.

When the field receives focus, a message appears under the field with the date format based on the user locale and date-style value. For example, if your user locale is en-US and the date-style is medium, the message displays "Format: Dec 31, 2024".

On desktop, lightning-input provides its own date/time picker that's styled with the Lightning Design System. Your Salesforce locale setting determines the acceptable date and time formats you can type in the fields and the format displayed in the fields after you pick a date and time. Your Salesforce language setting determines the names of months and weekdays displayed in the datepicker calendar, and the labels of the date and time fields.

The date and time you enter are automatically validated against your Salesforce locale format during the blur event. The date and time displayed reflect your Salesforce time zone setting. Use the timezone attribute to specify a different time zone in IANA time zone database format. For example, specify timezone="America/New_York" for US Eastern Time or timezone="GMT" for Greenwich Mean Time.

The component uses date-style="medium" by default to display the date in a medium-length style, such as Jan 7, 2020 in the en-US locale. To display a short style such as 1/7/2020, set date-style="short" in the component. To display a long style such as January 7, 2020, set date-style="long".

The date entered must be valid for the user's Salesforce locale, and match one of the short, medium, or long styles. If the date entered is valid, the component accepts the input and reformats it to the specified date-style during the blur event. For example, if the component specifies date-style="long" and a user enters 1/7/2020 in the en-US locale, the component reformats it to January 7, 2020.

The component accepts a month value of 13 to accommodate conditions that sometimes require a 13th month in a year. For most locales, if you enter 13 for the month, the component converts the date to the first month of the following year during the blur event.

The component uses time-style="short" by default to display the time without seconds, such as 6:53 PM in the en-US locale. To display time including seconds, set time-style="medium" or time-style="long". The medium and long styles currently have the same formatting.

Your Salesforce locale setting determines the time format you can type in the field or select in the timepicker, either 12-hr time with AM/PM or 24-hr time format.

Use the value attribute to optionally supply an initial value for the date and time as an ISO8601 formatted datetime string such as 2020-11-03T18:13:41Z.

Set min and max to ISO8601 formatted datetime strings to constrain the allowed date and time values.

If you set a min value, the datepicker calendar displays the month specified in the min value, and the previous month button is disabled. For example, if you specify min="2025-1-1", the calendar displays January 2025 and the previous month button is disabled.
If you set a max value, the datepicker calendar displays the month specified in the max value, and the next month button is disabled. For example, if you specify max="2025-12-31", the calendar displays December 2025 and the next month button is disabled.

The datepicker shows dates outside the min and max range in gray as a visual cue. Users can still select a date and time outside the range, but 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.

To validate a datetime input, use the required attribute to ensure a date and time are provided. Use min and max attributes to constrain the allowed datetime range. The component automatically validates the date and time format based on the user's Salesforce locale.

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

For the default error messages, see the lightning-input documentation.

To validate the datetime input in JavaScript, use the checkValidity() method. If one of the fields isn't valid, the reportValidity() method shows the error message below the first invalid field.

The validity attribute returns an object with read-only boolean properties. For the datetime 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 date is greater than the specified max attribute
rangeUnderflow - Indicates that the date 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"

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

On desktop, the datepicker calendar clips behind other components on the page if the parent container of lightning-input has a smaller width or height than the calendar. To prevent clipping, give the parent container a minimum width of 285px and minimum height of 310px.

In Lightning Experience, a datepicker calendar that's opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

Set the same time zone on your mobile device and in Salesforce to avoid confusion and potential validation issues. For example, suppose the current time is 4:00 PM ET. Your mobile device is set to the America/New_York time zone and you're interacting with Salesforce while it's set to the America/Los_Angeles time zone. When you tap an empty date/time field on the mobile device, the native date/time picker automatically selects the current device time, 4:00 PM.

Since the current time is 1:00 PM in Salesforce, this input time is in the future. If there's a validation rule stating that the value must be earlier than the current time, for example, the value is invalid. This occurs only because of the time zone discrepancy, and only on mobile devices when the date/time field is initially empty.

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

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

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

If the date or 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.

Parameter	Type	Description
value	string	Returns the input value.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	false	This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event.
composed	true	This event propagates outside of the component in which it was dispatched.

lightning-input

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