---
schema_version: "1"
id: 2808e8fab1f7cfe838bd388d20cdf25ea810bf3930bc12edddc132e627f4fa6e
title: Input Name
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputName/lightning-input-name.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-name.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 593a75d93d0bbf66da4aec6b41b99c29ea8d9964e237d0dbef8057006f7e5ca4
products:
  - Lightning Component Reference
---

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

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element](https://v1.lightningdesignsystem.com/components/form-element/)                               | [Form Element](https://www.lightningdesignsystem.com/components/form-element/)                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

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

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-input-name label="My Name" fields-to-display={fields}>
        </lightning-input-name>
    </div>
</template>
```
<!-- prettier-ignore-end -->

JavaScript file:

```javascript
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.

<!-- prettier-ignore-start -->
```html
<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>
```
<!-- prettier-ignore-end -->

JavaScript file:

```javascript
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.

<!-- prettier-ignore-start -->
```html
<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>
```
<!-- prettier-ignore-end -->

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

```js
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](#custom-events) section for a list of `event.target` properties. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).

## Use the Locale Information

In Lightning Experience, the `locale` value corresponds to the **Locale** field on the Language &amp; Time Zone page in the [user's personal settings](https://help.salesforce.com/s/articleView?id=xcloud.usersetup_lang_time_zone.htm).

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)](https://help.salesforce.com/s/articleView?id=xcloud.admin_supported_locales.htm).

<!-- prettier-ignore-start -->
```html
<lightning-input-name
    label="Contact Name"
    first-name="John"
    last-name="Doe"
    salutation="Mr."
    locale="fr-FR"></lightning-input-name>
```
<!-- prettier-ignore-end -->

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

<!-- prettier-ignore-start -->
```html
<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>
```
<!-- prettier-ignore-end -->

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

```javascript
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](https://developer.salesforce.com/docs/platform/lwc/guide/create-global-value-providers).

This component uses `button` elements for dropdown menus to comply with the [Lightning Design System combobox blueprint](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) 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`](/docs/platform/lightning-component-reference/guide/lightning-input.html) 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.

```javascript
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`](/docs/platform/lightning-component-reference/guide/lightning-input.html) 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.

| Parameter    | Type   | Description                           |
| ------------ | ------ | ------------------------------------- |
| salutation   | string | The value of the salutation field.    |
| firstName    | string | The value of the first name field.    |
| middleName   | string | The value of the middle name field.   |
| lastName     | string | The value of the last name field.     |
| informalName | string | The value of the informal name field. |
| suffix       | string | The value of the suffix field.        |
| validity     | object | The validity state of the element.    |

The `change` event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[Use Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components)

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

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

:::::

::::::