Input Name

lightning-input-name

Represents a name compound field.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="inputName" model="lwc" namespace="lightning"}

:::::

:::::tab

A lightning-input-name 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-input-name displays Salutation, First Name, and Last Name fields. Use the fields-to-display attribute to specify a different list of fields to display. The component supports these field names for fields-to-display.

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

Design

lightning-input-name implements the form element blueprint in the Salesforce Lightning Design System (SLDS). The input fields adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

Specify Field Names

To provide initial values for fields, specify the field names as attributes in the component by using the dash-separated format of the field names. For example, specify first-name instead of firstName. Use the options attribute to specify the values to display in the Salutation dropdown menu.

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

<template>
    <div>
        <lightning-input-name label="My Name" fields-to-display={fields}>
        </lightning-input-name>
    </div>
</template>

JavaScript file:

import { LightningElement } from "lwc";

export default class InputName extends LightningElement {
  fieldList = ["firstName", "lastName"];
  get fields() {
    return this.fieldList;
  }
}

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

<template>
    <div>
        <lightning-input-name
            label="Contact Name"
            first-name="John"
            middle-name="Middleton"
            last-name="Doe"
            informal-name="Jo"
            suffix="The 3rd"
            salutation="Mr."
            options={salutationOptions}
            fields-to-display={fields}
        >
        </lightning-input-name>
    </div>
</template>

JavaScript file:

import { LightningElement } from "lwc";

export default class InputName extends LightningElement {
  salutationsList = [
    { label: "Mr.", value: "Mr." },
    { label: "Ms.", value: "Ms." },
    { label: "Mrs.", value: "Mrs." },
    { label: "Dr.", value: "Dr." },
    { label: "Prof.", value: "Prof." },
  ];

  get salutationOptions() {
    return this.salutationsList;
  }

  fieldList = ["firstName", "lastName"];
  get fields() {
    return this.fieldList;
  }
}

lightning-input-name uses the onchange event handler to listen to a change to its field values.

<p>Your first name: {firstname}</p>
<lightning-input-name
    label="Name"
    first-name={firstname}
    middle-name="Middleton"
    last-name="Doe"
    options={salutationOptions}
    onchange={handleChange}></lightning-input-name>

To bind the input value on the name fields, use the event.target property.

import { LightningElement } from "lwc";

export default class InputNameBase extends LightningElement {
  firstname = "John";
  salutationsList = [
    { label: "Mr.", value: "Mr." },
    { label: "Ms.", value: "Ms." },
    { label: "Mrs.", value: "Mrs." },
    { label: "Dr.", value: "Dr." },
    { label: "Prof.", value: "Prof." },
  ];

  get salutationOptions() {
    return this.salutationsList;
  }

  handleChange(event) {
    this.firstname = event.target.firstName;
  }
}

See the Custom Events section for a list of event.target properties. For more information, see Data Binding in a Template.

Use the Locale Information

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-input-name 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).

<lightning-input-name
    label="Contact Name"
    first-name="John"
    last-name="Doe"
    salutation="Mr."
    locale="fr-FR"></lightning-input-name>

If you don't specify the locale attribute, lightning-input-name defaults to the user's locale setting in the org.

<h2>User's locale: {userLocale}</h2>
<!--No locale specified -->
<lightning-input-name
    lwc:ref="name"
    label="Contact Name"
    first-name="John"
    middle-name="Middleton"
    last-name="Doe"
    informal-name="Jo"
    suffix="The 3rd"
    salutation="Mr."
    fields-to-display={fields}></lightning-input-name>

In this example, the userLocale property returns ja-JP based on the org user's settings.

import { LightningElement } from "lwc";

export default class LocaleExample extends LightningElement {
  userLocale = "";

  fields = ["firstName", "lastName", "middleName", "salutation", "suffix", "informalName"];

  renderedCallback() {
    this.userLocale = this.refs.name.locale;
  }
}

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.

Usage Considerations

You can use custom labels that display translated values. For more information, see the Access Static Resources, Labels, Internationalization Properties, and User IDs.

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

Input Validation

When you set required, 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.

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 JavaScript. This validity attribute returns an object with boolean properties. For more information, see the lightning-input documentation.

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

handleClick: () => {
  var name = this.template.querySelector("lightning-input-name");
  var isValid = name.checkValidity();
  if (isValid) {
    alert("Creating new contact for " + this.name);
  } else {
    name.showHelpMessageIfInvalid();
  }
};

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.

Custom Events

change

The event fired when an item is changed in the lightning-input-name component.

The change event returns the following parameters.

The change event properties are as follows.

See Also

Use Wire Service with Base Components

Object Reference for the Salesforce Platform: Field Types

:::::

:::::tab ::component-specification{component="inputName" model="lwc" namespace="lightning"}

:::::

::::::