Input

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

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

The following HTML input types are not supported.

• button
• hidden
• image
• radio
• reset
• submit

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

Use lightning:radioGroup instead of input type radio for radio buttons.

If you're creating forms to interact with Salesforce records, consider using lightning:recordForm or lightning:recordEditForm.

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 a client-side controller 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.

This component implements the input blueprint in the in the Salesforce Lightning Design System (SLDS).

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:checkboxGroup instead.

The checkbox implements the checkbox blueprint in SLDS.

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 readonly="true" 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 readonly="true" specified, adding required="true" 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 dateStyle="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 dateStyle="short". To display a long style such as January 7, 2020 set dateStyle="long".

When the field receives focus, a message appears under the field with the date format based on the user locale and dateStyle value. For example, if your user locale is en-US and the dateStyle 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 dateStyle during the blur event. For example, if the component specifies dateStyle="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 limit the accepted 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 messageWhenRangeUnderflow and messageWhenRangeOverflow attributes.

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

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.

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 timeStepMinutes 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 dateStyle and timeStyle 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.

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 in dateStyle="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 01/07/2020, set dateStyle="short" in the component. To display a long style such as January 7, 2020 set dateStyle="long".

When the field receives focus, a message appears under the field with the date format based on the user locale and dateStyle value. For example, if your user locale is en-US and the dateStyle 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 dateStyle during the blur event. For example, if the component specifies dateStyle="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 timeStyle="short" by default to display the time without seconds, such as 6:53 PM in the en-US locale. To specify time including seconds, set timeStyle="medium" or timeStyle="long". The styles currently have the same formatting.

Use the value attribute to 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 limit the accepted 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 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 messages using the messageWhenRangeUnderflow and messageWhenRangeOverflow attributes.

You can guide users with a fieldLevelHelp 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.

Note: 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 messageWhenPatternMismatch 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 messageWhenTooLong 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 messageWhenTooShort 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.getSource().get("v.files");.

Your selected files are returned in a FileList object containing a list of File objects with these attributes:

• lastModified
• lastModifiedDate
• name
• size

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:fileUpload 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 attributes like 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 step 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 attribute returns an empty string. 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

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.

Number Shortcuts

Shortcuts such as k, K, m, and M 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 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.

Exponential Numbers

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.

Positive and Negative Signs

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

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.

Step

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.

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 fieldLevelHelp tooltip and a placeholder prompt in the password 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. You can handle this event using the onkeydown handler.

To indicate activity in the search field with a spinner, such as data loading, use the isLoading 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 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 timeStyle 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 timeStyle="short" by default, so the timepicker displays time without seconds. To display time including seconds, set timeStyle="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 messageWhenRangeUnderflow and messageWhenRangeOverflow attributes.

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

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 timeStepMinutes attribute. You can pass in an interval of 5 or more minutes.

On mobile devices, this component uses the native timepicker, which ignores the timeStyle 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 timeStyle="short" by default, so the timepicker displays time without seconds. To display time including seconds, set timeStyle="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 timepicker 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 messageWhenRangeUnderflow and messageWhenRangeOverflow attributes.

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

A checkbox toggle for selecting one of two given values. Use the messageToggleActive and messageToggleInactive 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.

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 length, use the maxlength 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 your client-side controller. 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 the client-side controller.

This validity attribute is a read-only object with the following 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.
• 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, or datetime input types.
• rangeUnderflow: Indicates that the value is less than the specified min attribute for number, range, date, or datetime 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 to true
• 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 the default message depending on the 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"

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 5 characters, the validity error returned is tooShort and the default message is "Your entry is too short." Use the messageWhenTooShort 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 client-side controller 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 are supported, 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 for more information.

To provide a hint for entering information in the field, specify help text with the fieldLevelHelp 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.

fieldLevelHelp 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. The placeholder text for date and time currently works only on desktop.

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 HTML <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 in lightning-input documentation for more information about these events.

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 aura:id to group and traverse the array of components. You can use get("v.checked") to determine which elements are checked or unchecked without reaching into the DOM. You can also use the name and value attributes to identify each component during the iteration.

The following example groups three checkboxes together using aura:id. The selected values are returned by clicking a button.

In your client-side controller, you can retrieve the array using cmp.find("colors") and inspect the checked values.

The selectionStart and selectionEnd attribute values are passed through to the <input> element for input type text. The selectionStart value specifies the index of the first character selected in the input element, while the selectionEnd 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 the client-side controller, 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 save vertical real estate and have fewer than 10 fields.

To group related fields together, such as individual parts of an address, use compound input components like lightning:inputAddress or lightning:inputLocation. For name fields, use lightning:inputName.

The label for an input field is displayed above the field by default. To display the label next to the field, use the label-inline variant.

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

You can use custom labels that display translated values. For more information, see the Lightning Aura Components Developer Guide.

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 ariaLabelledby 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 ariaInvalid 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 ariaInvalid is false. If the validity attribute returns a true value for any property other than valid, then ariaInvalid is true. When the component is initially loaded, ariaInvalid 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 dateAria* attributes. For example, use dateAriaDescribedBy to provide a descriptive label for the date field. To provide accessibility features to the time field, use the timeAria* attributes. For example, use timeAriaDescribedBy 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.