Input

A lightning-input component creates an HTML <input> element. This component supports the following input types:

• checkbox
• checkbox-button
• date
• datetime/datetime-local
• time
• email
• file
• password
• search
• tel
• url
• number
• text (default)
• toggle

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

The following HTML input types aren't supported.

• button
• hidden
• image
• radio
• reset
• submit
• week
• month

Use lightning-button instead for input types button, reset, and submit.

Use lightning-radio-group instead of input type radio for radio buttons.

Use lightning-combobox or input type number instead of input types week and month. The week and month types are browser-dependent and may cause issues with styling, accessibility, and general functionality in specific browsers.

When working with forms that interact with Salesforce records, consider using the record form components. The lightning-record-form, lightning-record-view-form, and lightning-record-edit-form components provide a form-based UI that's metadata-driven. The components are automatically wired up to your record data, labels, and field-level help text. For more information, see Work with Records Using Base Components.

Alternatively, to create your own custom UI to work with Salesforce records, use lightning-input with the lightning/ui*Api wire adapters and functions, such as getRecord and updateRecord. For more information, see Use the Wire Service with Base Components.

The label attribute is required. If you don't want to display a label, specify the variant="label-hidden" attribute. See Accessibility for more information.

You can define an action for input events like blur, focus, and change. For example, to handle a change event on the component when the value of the component is changed, use the onchange attribute. The component also provides a commit event, which the HTML <input> does not have. See Event Handling for details.

Checkboxes let you select one or more options. lightning-input type="checkbox" is useful for creating single checkboxes. If you are working with a group of checkboxes, use lightning-checkbox-group instead.

The checkbox implements the checkbox blueprint in SLDS.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Checkbox: Styling Hooks Overview for documentation on component-specific hooks for this component.

A checkbox that's disabled is grayed out and you can't interact with it. A disabled checkbox isn't focusable and isn't submitted with the form. Similarly, you can't interact with a read-only checkbox.

Unlike the native <input type="checkbox"> element, a read-only checkbox that you create using lightning-input with type="checkbox" and read-only attributes isn't focusable. You can't interact with a read-only checkbox and it isn't submitted with the form.

A read-only checkbox has these characteristics.

• Displays a checkmark icon without an enclosing border when the checked attribute is used.
• Displays a dotted square icon when the checked attribute isn't used.

If the checkbox also has read-only specified, adding the required attribute to a checkbox has no effect.

The read-only checkbox implements the checkbox (view mode) blueprint in SLDS.

Checkbox buttons let you select one or more options with an alternative visual design.

A color picker enables you to specify a color using a color picker or by entering the color into a text field.

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

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. For a list of default error messages, see Error Messages. You can specify your own error messages for the min and max validation errors using the message-when-range-underflow and message-when-range-overflow attributes.

You can guide users with a field-level-help tooltip and a placeholder prompt in the text field, as explained in Adding 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.

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.

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. For a list of default error messages, see Error Messages. You can specify your own error message using the message-when-range-underflow and message-when-range-overflow attributes.

You can guide users with a field-level-help tooltip, as explained in Adding 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.

An input field for entering an email address. UTF-8 encoding is supported for international email addresses. Valid email addresses include name@example and name@example.com. The email pattern is automatically validated during the blur event.

To restrict email input to match a certain pattern, use the pattern attribute to specify a regular expression. For example, pass in pattern=".+@example.com" to accept an email address only from the domain example.com. When using pattern, you can provide a custom validation error message using the message-when-pattern-mismatch attribute.

You can also include a hint of what a user can enter using the placeholder attribute. The placeholder text is displayed on the field before a user enters an input, but it doesn't validate input.

To specify the maximum number of characters for an email address, use the maxlength attribute. When using maxlength, you can provide a custom validation error message using the message-when-too-long attribute.

To specify the minimum number of characters for an email address, use the minlength attribute. When using minlength, you can provide a custom validation error message using the message-when-too-short attribute.

When multiple is used, the email field expects a single email address or a comma-separated list of email addresses. For example, my@example.com,your@example.com with or without a space after the comma.

An input field for selecting files to upload using an Upload Files button or a drag-and-drop zone. This field accepts files up to 3.5 MB.

To retrieve the list of selected files, use event.target.files in the onchange event handler.

Your selected files are returned in a FileList object, each specified as a File object with the size and type attributes.

• lastModified
• lastModifiedDate
• name
• size
• type

For more information on the File object, see MDN web docs: Getting information on selected files.

To handle file uploads in your org, wire up your component to an Apex controller that creates a ContentVersion and ContentVersionLink object.

Alternatively, use the lightning-file-upload component for an integrated way to upload files to records.

To programmatically add a file, assign the file input to a FileList object, a File object, or an array of File objects. For example, you can add a new file to the files that are already attached.

To remove all files from the file list, use one of these methods.

An input field for entering a number. When working with numerical input, you can use the attributes max, min, and step.

The attributes maxlength, minlength, and pattern can't be used with number type because they are for string data.

To specify valid increments for numerical fields, use the step attribute. The value of step constrains the numbers that users can enter. If you don't specify step, the default value of 1 allows users to enter only integers.

To enable decimal number entry, specify a value for step that represents the number of decimal places accepted and the increment. For example, specifying step=".01" permits numbers such as 0.99 and 123456.78. Specifying step=".20" permits numbers such as 18.60 but not 18.61 or 18.70.

If a user enters a number that doesn't match the step value, the browser flags it as invalid. Some browsers can round the number instead.

To format numerical input as a percentage or currency, set formatter to percent or currency respectively. To allow for decimal numbers, specify the step attribute as well.

For the percent formatter, the entered number is multiplied by 100 on blur to display the percentage. For example, when you enter .75 the value displays as 75%. When you enter 1, the value displays as 100%. To enter a percentage value as is, use formatter="percent-fixed". When you enter .75, the value displays as .75%, and when you enter 1, the value displays as 1%.

Number formatting is based on the Intl.NumberFormat object and follows ISO guidelines, displaying a value based on the org currency and your Salesforce locale. For example, when using formatter="currency" step=".01", entering "123.45" displays "€123,45" if your org's currency is set to EUR and your Salesforce locale is German. Your Salesforce locale is also used to determine if the number you entered is valid.

The number field does not let you type invalid characters, although anything can be pasted in. When a field contains invalid characters, a default field-level error is displayed on blur and the value property returns an empty string. The invalid input continues to be displayed to allow the user to correct the entry. See the Input Validation and Error Messages sections for more information. Valid characters include digits, number shortcuts, exponential numbers, positive and negative signs, and decimal separators.

The lightning-input component uses the Javascript parseFloat() function to convert input value strings to numbers. Very large numbers with more than approximately 15 or 16 total digits can lose precision and appear to be rounded. Browsers can handle this loss of numeric precision differently, causing variation in decimal point rounding.

For example, parseFloat("12345678901234.12345") is stored in memory as 12345678901234.123, which appears rounded. The parsed value in memory is used for validation, not the entered number. As a result, a number that should be invalid can be accepted as valid due to the loss of precision in the stored value. If your lightning-input component sets step="0.0001", the entered value 12345678901234.12345 is invalid. However, the stored value 12345678901234.123 is valid, so the entered value is accepted.

Digits are the numbers 0 to 9. Invalid placement of 0's are removed. For example, 010 results in 10. Trailing zeros after the decimal separator are also removed to match any given step pattern.

Shortcuts such as k, K, m, M, b, B, t, and T are allowed. For the en-US locale, when you enter 1k the field displays 1,000. Entering 1m results in 1,000,000. When the input field is focused, the input value is the multiplied number. For example, entering 1k results in 1,000 on blur, and 1000 when the input is focused again.

Shortcuts are not supported via the value attribute.

The letter e or E is accepted when entering an exponential number. For example, when you enter 2e2 the field displays 200 on blur, and 2e2 when the input is focused again.

Use + and - characters to represent positive and negative numbers. The positive + sign is removed on blur. If your number starts with +. or -., 0 is added before the decimal separator. For example, entering +.2 results in 0.2 on blur.

Decimal separators are valid when you use the step attribute. Only the . and , decimal separators are allowed. If your number starts with a decimal separator, 0 is added before the decimal separator. For example, entering .2 results in 0.2 on blur.

We recommend using a maximum of 9 decimal places for value and a maximum of 15 decimal places for step. Browsers exhibit inconsistencies in number calculation when you use more decimal places.

For example, a value of 9.9999999999 has more than 9 decimal places, and is interpreted as 10.0 by some browsers. If step is 0.01, stepMismatch validates as false when you enter 9.9999999999 because 10.0 matches the step. The messageWhenStepMismatch validation message isn't displayed and the field incorrectly displays as valid.

Similar behavior occurs when step has a value such as 0.000000000000001, which is more than 15 decimal places.

An input field for entering a password. Characters you enter are masked.

Use the value attribute to optionally supply an initial value for the password. Use pattern to pass a regular expression to validate the password characters.

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

A slider control for entering a number. When working with numerical input, you can use attributes like max, min, and step.

The attributes maxlength, minlength, and pattern can't be used with range type because they are for string data.

An input field for entering a search string. This field displays the Lightning Design System search utility icon.

A search field that contains a value displays an X button to clear the search. Press the button to remove the value on the field. It also fires the blur, change, and commit events in that order. When the Enter key is pressed, the search field fires the commit event.

To indicate activity in the search field with a spinner, such as data loading, include the is-loading attribute.

When a search field is invalid, the field is displayed with a red border and a red search icon. However, an error icon isn't displayed as it is for the other input types.

An input field for entering a telephone number. Use the pattern attribute to define a pattern for field validation.

An input field for entering text. This is the default input type.

The value attribute for this input type only supports string values. To clear a text field by setting the value attribute, use "" to specify an empty string because null isn't supported.

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

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.

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

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. For a list of default error messages, see Error Messages. You can specify your own error messages for the min and max validation errors using the message-when-range-underflow and message-when-range-overflow attributes.

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

A checkbox toggle for selecting one of two given values. Use the message-toggle-active and message-toggle-inactive attributes to specify labels displayed under the toggle for each state. By default the labels are Active and Inactive. To omit labels, set these attributes to empty strings.

A toggle is similar to a checkbox; it presents a binary choice. However, a toggle is self-contained and is designed to be used in a form with only one field. When you switch a toggle on or off, the change for that item should save immediately.

The toggle implements the checkbox toggle blueprint in SLDS.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Checkbox Toggle: Styling Hooks Overview for documentation on component-specific hooks for this component.

By default, the toggle component expands to 100% of the available width. To limit the size of the toggle component, wrap it with an element that specifies the appropriate width.

An input field for entering a URL. The address must include the protocol, such as http:// or ftp://. The URL pattern is automatically validated during the blur event. To enter the address without the protocol, such as www.example.com, use the default type="text" instead.

Client-side input validation is available for this component. An invalid field is displayed with a red border and an error icon next to the field. An error message in red text is also displayed below the field. For example, an error message is displayed when a URL or email address is expected for an input type of url or email. Note that disabled and read-only inputs are always valid.

An error icon is displayed on fields that are in an invalid state for these input types.

• email
• number
• password
• range
• tel
• text
• url

An error icon is displayed on fields, except on desktop browsers, for these input types.

• date
• datetime
• datetime-local
• time

You can define additional field requirements. For example, to set a maximum value on a number field, use the max attribute.

To check the validity states of an input, use the validity attribute, which is based on the Constraint Validation API. To determine if a field is valid, you can access the validity states in JavaScript. Let's say you have the following input field.

The validity attribute returns true for the valid property because all constraint validations are met, and in this case there are none.

For example, you have the following form with several fields and a button. To display error messages on invalid fields, use the reportValidity() method.

Validate the fields in JavaScript.

This validity attribute returns an object with the following read-only boolean properties. One property is set to true and the rest are false, depending on attributes set on the input field and the user's entry.

• badInput: Indicates that the value is invalid for any input type.
• customError: Indicates that a custom error has been set. See Custom Validity Error Messages.
• patternMismatch: Indicates that the value doesn't match the specified pattern attribute for email, password, search, tel, text, or url input types.
• rangeOverflow: Indicates that the value is greater than the specified max attribute for number, range, date, datetime, or time input types.
• rangeUnderflow: Indicates that the value is less than the specified min attribute for number, range, date, datetime, or time input types.
• stepMismatch: Indicates that the value doesn't match the specified step attribute for number or range input types.
• tooLong: Indicates that the value exceeds the specified maxlength attribute for email, password, search, tel, text, or url input types.
• tooShort: Indicates that the value is less than the specified minlength attribute for email, password, search, tel, text, or url input types.
• typeMismatch: Indicates that the value doesn't match the required syntax for email or url input types.
• valueMissing: Indicates that an empty value is provided when required attribute is set for any input type.
• valid: True if none of the preceding properties are true.

When an input validation fails, a default message is displayed. You can provide your own values for the error messages to override the default messages. Specify your message using an attribute that corresponds to the validity error that's returned, as shown in the following table.

Note that 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"

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 MMM d, yyyy"

To override the default error message, use the corresponding attribute. For example, you have a text input with a minimum length of 5. If users enter fewer than five characters, the validity error returned is tooShort and the default message is "Your entry is too short." Use the message-when-too-short attribute to display a different error message.

Custom errors that override the default error message are appended with the string "(Use format [format])" where [format] is the date format that's determined by the user locale. For example, if your component sets badInput="This is a custom error", the displayed error for a date field in en-US locale is "This is a custom error (Use format Dec 31, 2024)".

The component supports setCustomValidity() from HTML5's Constraint Validation API. To set an error message, provide a quoted string to display. To reset the error message, set the message to an empty string (""). See details at https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity.

This example shows how to display a custom error message with setCustomValidity() and reportValidity(). The component is a simple text input with a button.

The register() function compares the input entered by the user to a particular text string. If true, setCustomValidity() sets the custom error message. The error message is displayed immediately using reportValidity().

Note that when the comparison isn't true, you should set the error message to an empty string to zero out any messages that might have been set on previous calls.

Some input types can be autofilled, based on your browser's support of the feature. The autocomplete attribute passes through its value to the browser. These lightning-input types support the autocomplete attribute:

• email
• search
• tel
• text
• url

The values on and off or a space-separated string of expected data types are supported, but the behavior depends on the browser. Some browsers might ignore the passed value.

To provide autocomplete guidance on the expected data type in the field, use a space-separated string that describes the meaning of the autocompletion value. For example autocomplete="shipping street-address". For more information, see the MDN web docs.

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

To provide sample input in the field, use the placeholder attribute. For example, in a url input, show a URL in the correct format.

field-level-help isn't supported for file, toggle, and checkbox-button types.

placeholder is supported for date, email, number, password, search, tel, text, time, and url input types only. The placeholder support for date and time is a Salesforce addition and is not part of the HTML5 standard.

Bind the input value to a property in your component's JavaScript class. lightning-input uses the onchange event handler to listen a change to its value. For more information, see Data Binding in a Template.

The native HTML <input> element provides two events, input and change. The lightning-input component provides two custom events, change and commit.

The component's change event behaves the same as the native input and change events together. It fires whenever you change the input value, as the <input> element's input event does. It also fires when you finish changing the input, as the <input> element's change event does.

The component's commit event fires only when you finish changing the input, which is the same behavior as the HTML <input> element's change event.

The component doesn't provide an input event because the behavior is provided in the change event.

To summarize, the component's change event is equivalent to the input and change events of the <input> element. The component's commit event is equivalent to the change event of the <input> element.

The change event fires at different times, depending on the specific input type. For information about the change event for the <input> element, see developer.mozilla.org.

See the Custom Events section for more information about the component's events.

This example shows how you can clear the input value using the change event. When the button is clicked, it calls handleClear() to reset text to an empty string.

If you use the commit event here, the commit event isn't fired if you try to clear the input value and it matches the previously committed value. For example, entering "hello" and clearing the value, and then entering "hello" again and attempting to clear the value. The second attempt doesn't clear the value because the commit event isn't called. this.text remains an empty string even though the input value displays "hello".

In general, use oncommit to handle changes to number inputs. Use onchange for use cases where you want to process each character entered right away. For example, use onchange if you want to echo the content entered in another field as it is entered.

For input type number, the component sets the value to '' (an empty string) when the number input becomes invalid. The change event is fired each time the value changes, even when the value is set to an empty string. This enables you to reset the field in your onchange handler when input is invalid. Use separate variables to set the value of the number input and retrieve it.

When working with checkboxes and toggle switches, use this.template.querySelectorAll to retrieve the array of components. You can use .filter to determine which elements are checked or unchecked. The following example displays the values of the selected checkboxes.

When you select a checkbox, the handleCheckboxChange function updates the selection property to display a list of selected checkboxes.

To programmatically set a checkbox or checkbox button to checked, query the element using a custom data attribute. You can't query the internal elements of a Lightning web component. This example uses a custom attribute data-element to query the element. The checkbox is selected by clicking a button.

Set the element's checked property to true.

The selection-start and selection-end attribute values are passed through to the <input> element. Only the input type text is currently supported. The selection-start value specifies the index of the first character selected in the input element, while the selection-end value specifies the index of the last character selected. Index values start at 0.

This example selects the characters from index 0 to the end when you click the button.

In JavaScript, the selectionEnd property is set to the length of the current input value.

For a single line of plain text input, use lightning-input. For multiple lines of plain text input, use lightning-textarea instead. For more specific input such as with numbers or email addresses, use the type attribute. Specifying type ensures that built-in validation can be applied to your data input.

In most contexts, a stacked label (standard or label-stacked variant) results in better readability and clarity. Use horizontal labels (label-inline variant) only if you need to conserve vertical space and have fewer than 10 fields.

To group related fields together, such as individual parts of an address, use compound input components like lightning-input-address or lightning-input-location. For name fields, use lightning-input-name.

lightning-input implements the input blueprint in the Salesforce Lightning Design System (SLDS).

To apply additional styling, use the SLDS utility classes with the class attribute.

This example creates two fields using lightning-input in a compound row similar to the SLDS form fields.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Input: Styling Hooks Overview for documentation on component-specific hooks for this component.

maxlength limits the number of characters you can enter. The message-when-too-long error message isn't triggered because you can't type more than the number of characters allowed. However, you can use the message-when-pattern-mismatch and pattern attributes to trigger a message on blur when too many characters are entered.

You can use custom labels that display translated values on input fields. For more information, see Access Labels.

You must provide a text label for accessibility to make the information available to assistive technology. The label attribute creates an HTML <label> element for your input component. To hide a label from view and make it available to assistive technology, use the label-hidden variant.

Specify the aria-labelledby attribute and variant="label-hidden" to provide a custom label for assistive devices. Although the label attribute is still required, the <label> element is not rendered in this case.

lightning-input sets the aria-invalid attribute to match the validity state of the input field for assistive technology. If the validity attribute returns a true value for the valid property, then aria-invalid is false. If the validity attribute returns a true value for any property other than valid, then aria-invalid is true. When the component is initially loaded, aria-invalid is set to false. This prevents fields that are marked required from being announced as invalid before you enter anything.

When a field-level error is displayed, lightning-input links the input field to the error message using the aria-describedby attribute, which enables assistive technology to announce the error message on the input field.

For the datetime type, the component renders two separate fields for date and time input. To provide accessibility features to the date field, use the date-aria-* attributes. For example, use date-aria-described-by to provide a descriptive label for the date field. To provide accessibility features to the time field, use the time-aria-* attributes. For example, use time-aria-described-by to provide a descriptive label for the time field.

In some cases, you can further improve the accessibility of your lightning-input implementation by specifying the autocomplete attribute. For supported types, see the Using Autocomplete in Input Fields section.

Use the autocomplete attribute to make it easier for a browser to prefill values in forms. For example, specify autocomplete="given-name" on lightning-input to expect the field value to be the user's first name. The field displays a list of options that anticipates what a user is typing. The user presses the Down arrow key to select an option and press Enter. For more information, see WCAG 2.2: Using autocomplete attributes.

The autocomplete attribute is helpful for fields that specifically ask for data about the user who's completing the form. Don't use the autocomplete attribute on a field that asks for data about other people. The list of suggested values can come from past values entered by the user or they can be pre-configured on the user's browser.

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.

commit

The event fired when you press Enter after interacting with the input, or move away from the input so it loses focus. For the input type search, the event is fired when focus leaves the entire component or when the user clicks the X button to clear the search. The event is also fired when you press the Enter key. For the input type number the event is also fired when you press Up/Down arrow keys to change the number.

The commit event doesn’t return any parameters.

The event properties are as follows.

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning-input, see the following components in the LWC Recipes repo.

• c-lds-create-record
• c-misc-modal
• c-wire-get-picklist-values

Access Elements the Component Owns