Input

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

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

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

These HTML input types aren't supported.

• button - Use lightning-button instead.
• hidden - Use lightning-record-edit-form instead.
• image - Use lightning-button or an <img> tag instead.
• radio- Use lightning-radio-group instead.
• reset - Use lightning-button instead.
• submit - Use lightning-button instead.
• week - Use lightning-combobox or lightning-input with the number type instead.
• month - Use lightning-combobox or lightning-input with the number type instead.

The week and month types are browser-dependent and can cause issues with styling, accessibility, and general functionality in specific browsers.

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.

These input types-email, number, password, search, tel, text, url-use the same SLDS design.

For other input types, see these documentation resources.

• checkbox
• checkbox-button
• checkbox-toggle
• color
• date
• datetime
• file
• time
• range

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 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 described in Add Field-Level Help and Placeholder Text.

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.

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 this 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 these 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.

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 your 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. You can also define an action for input events like blur and focus.

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. Some input types don't support the commit event.

• checkbox
• date
• datetime
• file
• time
• toggle

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.

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.

Use a combination of variants and utility classes to customize your input fields.

Use the variant attribute with one of these values to position the labels differently relative to the fields.

• standard is the default, which displays the label above the field.
• label-hidden hides the label but make it available to assistive technology. If you provide a value for field-level-help, the tooltip icon is still displayed.
• label-inline aligns the label and field horizontally.
• label-stacked places the label above the field.

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

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 provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Consider these usage guidelines.

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

When working with forms that interact with Salesforce records, consider using these components instead: 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.

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 Use 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

Object Reference for the Salesforce Platform: Field Types