Input Name

A lightning:inputName component is a name compound field represented by HTML input elements of type text. The Salutation field is a dropdown menu that accepts an array of label-value pairs.

By default, lightning:inputName displays Salutation, First Name, and Last Name fields. Use the fieldsToDisplay attribute to specify a different list of fields to display. The component supports these field names.

• firstName
• lastName
• middleName
• informalName
• suffix
• salutation

To provide initial values for fields, specify the field names as attributes in the component. Use the options attribute to specify the values to display in the Salutation dropdown menu.

This example creates a simple input name field, consisting of just the First Name and Last Name fields, without specifying initial values. The rendered fields display default placeholder text.

1<aura:component>
2  <aura:attribute name="fields" type="List" default="['firstName', 'lastName']" />
3  <div>
4    <lightning:inputName aura:id="myname" label="My Name" fieldsToDisplay="{!v.fields}" />
5  </div>
6</aura:component>

This example creates an input name field that specifies values for first name, middle name, last name, informal name, and suffix. The Salutation dropdown menu is set to display “Mr.” by default. The fieldsToDisplay attribute determines which fields are rendered. Although all possible fields are specified inside the component, only the First Name and Last Name display.

1<aura:component>
2  <aura:attribute
3    name="salutationOptions"
4    type="List"
5    default="[
6        {'label': 'Mr.', 'value': 'Mr.'},
7        {'label': 'Ms.', 'value': 'Ms.'},
8        {'label': 'Mrs.', 'value': 'Mrs.'},
9        {'label': 'Dr.', 'value': 'Dr.'},
10        {'label': 'Prof.', 'value': 'Prof.'},
11    ]"
12  />
13  <aura:attribute name="fields" type="List" default="['firstName', 'lastName']" />
14  <div class="slds-size_1-of-2">
15    <lightning:inputName
16      aura:id="contactname"
17      label="Contact Name"
18      firstName="John"
19      middleName="Middleton"
20      lastName="Doe"
21      informalName="Jo"
22      suffix="The 3rd"
23      salutation="Mr."
24      options="{!v.salutationOptions}"
25      fieldsToDisplay="{!v.fields}"
26    />
27  </div>
28</aura:component>

To display all the fields in this example, set the fields attribute as follows:

1<aura:attribute
2  name="fields"
3  type="List"
4  default="['firstName', 'lastName', 'middleName', 'informalName', 'suffix', 'salutation']"
5/>

When you set required="true", a red asterisk is displayed on the Last Name field to indicate that it’s required. An error message is displayed below the Last Name field if a user interacted with it and left it blank. The required attribute is not enforced and you must validate it before submitting a form that contains a name compound field.

Let’s say you have a lightning:button component that calls the handleClick controller action. You can display the error message when a user clicks the button without providing a value for the Last Name field.

1({
2  handleClick: function (cmp, event) {
3    var name = cmp.find("myname");
4    var isValid = name.checkValidity();
5    if (isValid) {
6      alert("Creating new contact for " + name.get("v.lastName"));
7    } else {
8      name.showHelpMessageIfInvalid();
9    }
10  },
11});

To check the validity states of an input, use the validity attribute, which is based on the ValidityState object of the Constraint Validation API. You can access the validity states in your client-side controller. This validity attribute returns an object with boolean properties.

You can override the default message by providing your own value for messageWhenValueMissing.

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidityForField() and reportValidity(). For more information, see the lightning:input documentation.

In Lightning Experience, the locale value corresponds to the Locale field on the Language & Time Zone page in the user’s personal settings .

By default, your org’s locale setting determines the order of the name fields.

For example, if you select “Japanese (Japan)” in the Locale field, lightning:inputName uses ja-JP as the locale.

To override the locale on your user’s settings, provide your own locale value. Specify any locale code from the list of Supported Number, Name, and Address Formats (ICU) .

1<aura:component>
2  <aura:attribute name="fields" type="List" default="['firstName', 'lastName', 'salutation']" />
3  <div>
4    <lightning:inputName
5      label="Name"
6      firstName="John"
7      middleName="Middleton"
8      salutation="Mr."
9      locale="fr-FR"
10      fieldsToDisplay="{!v.fields}"
11    />
12  </div>
13</aura:component>

If you don’t specify the locale attribute, lightning:inputName defaults to the user’s locale setting in the org.

If you pass in an invalid locale, the component uses en-US. The locale supports both hyphens and underscores, for example, en-US or en_US.

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

This component uses button elements for dropdown menus to comply with the Lightning Design System combobox blueprint for select-only comboboxes.