Date Picker

lightning-input type="date"

For Use In

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

A date input field includes a text input to type a date and a datepicker to select a date.

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
date	Datepickers	Datepickers

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

On desktop, this component uses a datepicker styled with the Lightning Design System. This picker uses the user's Salesforce language setting for names of months and weekdays, and the user's Salesforce locale setting for the date format. The entered date is validated against the user's Salesforce locale format during the blur event.

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".

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".

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 you enter 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.

Use the value attribute to supply an initial value for the date as an ISO8601 formatted date string, such as 2020-11-03.

Set min and max to ISO8601 formatted date strings to constrain the allowed date 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. Although users can select a date 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.

To provide sample input in the field, use the placeholder attribute. For example, in a date input, show the date in the expected format.

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

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

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

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

The validity attribute returns an object with read-only boolean properties. For the date 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 and a placeholder prompt in the text field, 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.

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

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 date field.

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

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

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