lightning:input (Beta)

Represents interactive controls that accept user input depending on the type attribute.

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 Validation

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

  • badInput: Indicates that the value is invalid
  • patternMismatch: Indicates that the value doesn't match the specified pattern
  • rangeOverflow: Indicates that the value is greater than the specified max attribute
  • rangeUnderflow: Indicates that the value is less than the specified min attribute
  • stepMismatch: Indicates that the value doesn't match the specified step attribute
  • tooLong: Indicates that the value exceeds the specified maxlength attribute
  • typeMismatch: Indicates that the value doesn't match the required syntax for an email or url input type
  • valueMissing: Indicates that an empty value is provided when required attribute is set to true
Error Messages

When an input validation fails, the following messages are displayed by default.

  • badInput: Enter a valid value.
  • patternMismatch: Your entry does not match the allowed pattern.
  • rangeOverflow: The number is too high.
  • rangeUnderflow: The number is too low.
  • stepMismatch: Your entry isn't a valid increment.
  • tooLong: Your entry is too long.
  • typeMismatch: You have entered an invalid format.
  • valueMissing: Complete this field.

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." />
Usage Considerations

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

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.

Methods

This component supports the following method.

focus(): Sets the focus on the element.

Attributes

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.