A lightning:input component creates an HTML input element. This component supports HTML5 input types, including email, password, tel, url, number, checkbox, toggle, radio, date and datetime. The default is text.
This component inherits styling from forms in the Lightning Design System.
lightning:input provides several HTML equivalent attributes for input, such as placeholder, maxlength, minlength, and pattern. When working with numerical input, you can use attributes like max, min, and step. When working with checkboxes, toggles, and radio buttons, you can use the checked attribute to define their selected state.
For example, to set a maximum length, use the maxlength attribute.
<lightning:input name="quantity" value="1234567890" label="Quantity" maxlength="10" />
To format numerical input as a percentage or currency, set formatter to percent or currency respectively.
<lightning:input type="number" name="ItemPrice" label="Price" value="12345" formatter="currency"/>
You can define a client-side controller action for input events like onblur, onfocus, and onchange. For example, to handle a change event on the component when the value of the component is changed, use the onchange attribute.
Input ValidationClient-side input validation is available for this component. For example, an error message is displayed when a URL or email address is expected for an input type of url or email.
To check the validity states of an input, use the validity attribute, which is based on the ValidityState object. You can access the validity states in your client-side controller. It returns null if the user has not interacted with the input element. Otherwise, it returns an object with the following boolean properties.
When an input validation fails, the following messages are displayed by default.
You can override the default messages by providing your own values for these attributes: messageWhenBadInput, messageWhenPatternMismatch, messageWhenTypeMismatch, messageWhenValueMissing, messageWhenRangeOverflow, messageWhenRangeUnderflow, messageWhenStepMismatch, messageWhenTooLong.
For example, you want to display a custom error message when the input is less than five characters.
<lightning:input name="firstname" label="First Name" minlength="5" messageWhenBadInput="Your entry must be at least 5 characters." />
Date pickers in fields of type date and datetime-local don't currently inherit the Lightning Design System styling. Additionally, fields for percentage and currency input must specify a step increment of 0.01 as required by the native implementation.
<lightning:input type="number" name="percentVal" label="Enter a percentage value" formatter="percent" step="0.01" /> <lightning:input type="number" name="currencyVal" label="Enter a dollar amount" formatter="currency" step="0.01" />
When working with checkboxes, radio buttons, 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.
<aura:component> <form> <fieldset> <legend>Select your favorite color:</legend> <lightning:input type="checkbox" label="Red" name="color1" value="1" aura:id="colors"/> <lightning:input type="checkbox" label="Blue" name="color2" value="2" aura:id="colors"/> <lightning:input type="checkbox" label="Green" name="color3" value="3" aura:id="colors"/> </fieldset> <lightning:button label="Submit" onclick="{!c.submitForm}"/> </form> </aura:component>
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.
MethodsThis component supports the following method.
focus(): Sets the focus on the element.
Attribute Name | Attribute Type | Description | Required? |
---|---|---|---|
accesskey | String | Specifies a shortcut key to activate or focus an element. | |
body | Component[] | The body of the component. In markup, this is everything in the body of the tag. | |
checked | Boolean | Specifies whether the checkbox is checked. This value defaults to false. | |
class | String | A CSS class for the outer element, in addition to the component's base classes. | |
disabled | Boolean | Specifies that an input element should be disabled. This value defaults to false. | |
formatter | String | String value with the formatter to be used. | |
label | String | Text label for the input. | Yes |
max | Decimal | Expected higher bound for the value in Floating-Point number | |
maxlength | Integer | The maximum number of characters allowed in the field. | |
messageWhenBadInput | String | Error message to be displayed when a bad input is detected. | |
messageWhenPatternMismatch | String | Error message to be displayed when a pattern mismatch is detected. | |
messageWhenRangeOverflow | String | Error message to be displayed when a range overflow is detected. | |
messageWhenRangeUnderflow | String | Error message to be displayed when a range underflow is detected. | |
messageWhenStepMismatch | String | Error message to be displayed when a step mismatch is detected. | |
messageWhenTooLong | String | Error message to be displayed when the value is too long. | |
messageWhenTypeMismatch | String | Error message to be displayed when a type mismatch is detected. | |
messageWhenValueMissing | String | Error message to be displayed when the value is missing. | |
min | Decimal | Expected lower bound for the value in Floating-Point number | |
minlength | Integer | The minimum number of characters allowed in the field. | |
name | String | Specifies the name of an input element. | Yes |
onblur | Action | The action triggered when the element releases focus. | |
onchange | Action | The action triggered when a value attribute changes. | |
onfocus | Action | The action triggered when the element receives focus. | |
pattern | String | Specifies the regular expression that the input's value is checked against. This attributed is supported for text, date, search, url, tel, email, and password types. | |
placeholder | String | Text that is displayed when the field is empty, to prompt the user for a valid entry. | |
readonly | Boolean | Specifies that an input field is read-only. This value defaults to false. | |
required | Boolean | Specifies that an input field must be filled out before submitting the form. This value defaults to false. | |
step | Object | Granularity of the value in Positive Floating Point. Use 'any' when granularity is not a concern. | |
tabindex | Integer | Specifies the tab order of an element (when the tab button is used for navigating). | |
type | String | The type of the input. This value defaults to text. | |
validity | Object | Represents the validity states that an element can be in, with respect to constraint validation. | |
value | Object | Specifies the value of an input element. |