Input Address

A lightning-input-address component creates a compound field that includes these constituent fields.

• Street
• City
• Province
• Country
• Postal code

The street field is a multi-line text field. The other fields are individual text input fields by default. The country and province fields use dropdown menus if you specify country-options and province-options to provide options for menu items.

To specify the initial field values, use the component attributes. This example creates an address compound field with attributes to specify values for the constituent fields.

1<template>
2    <div>
3        <lightning-input-address
4            address-label="Address"
5            street-label="Street"
6            city-label="City"
7            country-label="Country"
8            province-label="State"
9            postal-code-label="PostalCode"
10            street="1 Market St."
11            city="San Francisco"
12            country="US"
13            province="CA"
14            postal-code="94105"
15            field-level-help="Enter your billing address"
16        >
17        </lightning-input-address>
18    </div>
19</template>

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

1<p>You are located in: {city}</p>
2    <lightning-input-address
3        address-label="Address"
4        street-label="Street"
5        city-label="City"
6        country-label="Country"
7        province-label="Province"
8        postal-code-label="PostalCode"
9        city={city}
10        onchange={handleChange} ></lightning-input-address>

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

1import { LightningElement } from "lwc";
2
3export default class AddressCityExample extends LightningElement {
4  city = "San Francisco";
5
6  handleChange(event) {
7    this.city = event.target.city;
8  }
9}

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

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

To create a dropdown menu for the country and province, pass in an array of label-value pairs to country-options and province-options. Use the country and province attributes to specify the default values on the dropdown menus.

1<template>
2    <div>
3        <lightning-input-address
4            address-label="Address"
5            street-label="Street"
6            city-label="City"
7            country-label="Country"
8            province-label="Province/State"
9            postal-code-label="PostalCode"
10            street="1 Market St."
11            city="San Francisco"
12            province="CA"
13            country="US"
14            country-options={getCountryOptions}
15            province-options={getProvinceOptions}
16            postal-code="94105"
17            required
18            onchange={handleChange}
19        >
20        </lightning-input-address>
21    </div>
22</template>

JavaScript file:

1import { LightningElement } from "lwc";
2
3export default class DemoInputAddress extends LightningElement {
4  provinceOptions = [
5    { label: "California", value: "CA" },
6    { label: "Texas", value: "TX" },
7    { label: "Washington", value: "WA" },
8  ];
9
10  countryOptions = [
11    { label: "United States", value: "US" },
12    { label: "Japan", value: "JP" },
13    { label: "China", value: "CN" },
14  ];
15
16  get getProvinceOptions() {
17    return this.countryProvinceMap[this._country];
18  }
19  get getCountryOptions() {
20    return this.countryOptions;
21  }
22
23  handleChange(event) {
24    this._country = event.detail.country;
25  }
26}

Alternatively, you can enable state and country picklists in your org, and access the values by using a wire adapter. See Let Users Select State and Country from Picklists in Salesforce Help and getPicklistValues in the Lightning Web Components Developer Guide.

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 and layout of the address fields.

For example, if you select “French (France)” in the Locale field, lightning-input-address uses fr-FR 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<template>
2    <lightning-input-address
3        address-label="Address"
4        street-label="Street"
5        city-label="City"
6        country-label="Country"
7        province-label="Province"
8        postal-code-label="Postal Code"
9        locale="en-US"></lightning-input-address>
10</template>

If you don’t specify the locale, lightning-input-address defaults to the user’s locale in the org.

1<template>
2    <h2>User's locale: {userLocale}</h2>
3    <!--No locale specified on lightning-input-address -->
4    <lightning-input-address
5        lwc:ref="address"
6        address-label="Address"
7        street-label="Street"
8        city-label="City"
9        country-label="Country"
10        province-label="Province"
11        postal-code-label="Postal Code"></lightning-input-address>
12</template>

In this example, the userLocale property returns fr-FR based on the org user’s settings.

1import { LightningElement } from "lwc";
2
3export default class LocaleExample extends LightningElement {
4  userLocale = "";
5
6  renderedCallback() {
7    this.userLocale = this.refs.address.locale;
8  }
9}

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.

The province field is used with countries that include a province in their addresses. This field can also be used as a field for state information, such as in United States addresses.

To visually hide the province field from the component’s fields layout for locales that don’t require it, use the hide-province attribute. For example, you can use hide-province when the locale is fr-FR or zh-CN.

1<template>
2     <lightning-input-address
3        address-label="Address"
4        street-label="Street"
5        city-label="City"
6        country-label="Country"
7        province-label="Province"
8        postal-code-label="Postal Code"
9        locale="fr-FR"
10        hide-province
11    ></lightning-input-address>
12</template>

If you don’t provide a value for province-label, the component renders with a province field without a label. Hide the field using hide-province.

To enable autocompletion of the address fields using an address lookup field, include the show-address-lookup attribute. The address lookup field is placed above the address fields you provide.

1<template>
2    <lightning-input-address
3        show-address-lookup
4        address-label="Address"
5        street-label="Street"
6        city-label="City"
7        country-label="Country"
8        province-label="State"
9        postal-code-label="Zip Code"
10        street="1 Market St."
11        city="San Francisco"
12        country="US"
13        province="CA"
14    >
15    </lightning-input-address>
16</template>

When you start typing an address in the lookup field, a dropdown menu displays matching addresses returned by the Google Maps Places API. Select an address from the dropdown to populate the address fields.

When location services is enabled on your browser, the component uses the browser’s Geolocation API to determine the initial location. A timeout can occur due to factors such as browser security settings, network conditions, and device capabilities. If the Geolocation API times out after 10 seconds, the address lookup field defaults to San Francisco, CA with a latitude of 37.790091 and longitude of -122.396848 instead of your current position. To enable location services on your browser, see Autocomplete Addresses in Salesforce Help.

To filter address lookups by country, pass in an array of ISO 3166-1 Alpha-2 country code strings to the country-lookup-filter attribute. Country codes are case-insensitive. Enable address lookup by including show-address-lookup.

1<template>
2    <lightning-input-address
3        show-address-lookup
4        address-label="Address"
5        street-label="Street"
6        city-label="City"
7        province-label="State"
8        country-label="Country"
9        postal-code-label="Zip Code"
10        country-lookup-filter={countries}
11    >
12    </lightning-input-address>
13</template>

In your JavaScript file, pass in a list of country codes. You can specify a maximum of five country codes.

1import { LightningElement } from "lwc";
2
3export default class CountryFilterExample extends LightningElement {
4  countries = ["AU", "GB", "JP"];
5}

For a list of valid country codes, see Google for Developers: countries.csv.

By default, the Street address field is a textarea field. Use compact address fields if you want to separate the Street address field into two input fields instead.

To display compact address fields, include the show-compact-address attribute. Use street-label to provide a label for the first line of address, and use subpremise-label for the second line of address. You can add supplementary information on this field, such as a building number or unit name.

1<lightning-input-address
2    show-compact-address
3    address-label="Address"
4    street-label="Street Line 1"
5    subpremise-label="Street Line 2"
6    city-label="City"
7    country-label="Country"
8    province-label="Province"
9    postal-code-label="Postal Code"></lightning-input-address>

To enable compact address fields with address lookup, include the show-address-lookup and show-compact-address attributes. These attributes enable the first street address field as a lookup field.

1<lightning-input-address
2    show-address-lookup
3    show-compact-address
4    address-label="Address"
5    street-label="Street Line 1"
6    city-label="City"
7    country-label="Country"
8    province-label="Province"
9    postal-code-label="Postal Code"></lightning-input-address>

When you start typing an address in the lookup field, a dropdown menu displays matching addresses returned by the Google Maps Places API. Select an address from the dropdown to populate the address fields.

Subpremise information includes apartment, unit, or floor number. To provide a label on the subpremise field, use the subpremise-label attribute. The second address field is used as the subpremise field.

You can provide a subpremise value using the subpremise attribute. The first input field continues to use street-label. The subpremise field doesn’t require a value for submission.

1<lightning-input-address
2    show-address-lookup
3    show-compact-address
4    address-label="Address"
5    street-label="Street Line 1"
6    subpremise-label="Street Line 2"
7    city-label="City"
8    country-label="Country"
9    province-label="Province"
10    postal-code-label="Postal Code"></lightning-input-address>

Google Maps API currently supports subpremises for Australia, New Zealand, and Canada only. The placement of subpremise information is different for each country. For example, Australian addresses include the subpremise information as a prefix to street number, such as 2/1 Tully Road where 2 is the subpremise. When you enter this address and select it from the search results, the street field is populated with the subpremise and street information while the subpremise field remains empty.

Populating the subpremise field using address lookup isn’t currently supported. For example, US addresses include the subpremise after the street number, such as 123 Main St, Unit 10. When you enter the address with a subpremise, the subpremise appears with the street address in the result list. However, selecting the address from the search result doesn’t populate the subpremise field. The street field also doesn’t preserve the subpremise, but you can enter it manually in the street or subpremise field.

When you set required, a red asterisk is displayed on every address field to indicate that an entry in each field is required. An error message is displayed below a 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 an address compound field.

Let’s say you have a lightning-button component that calls the handleClick function. You can display the error message when a user clicks the button without providing a value on a field.

1handleClick(e) {
2        const address =
3            this.template.querySelector('lightning-input-address');
4        const isValid = address.checkValidity();
5        if(isValid) {
6            alert("Creating a new address");
7        } else {
8            alert("Complete all address fields");
9        }
10    }

A label is associated with an address field and it enables screen readers to navigate the form correctly. Include a label for each field you’re using, with the following attributes.

• address-label
• street-label
• city-label
• province-label
• country-label
• postal-code-label

You can hide the address-label visually and still make them accessible to screen readers by using variant="label-hidden".

Additionally, the show-address-lookup boolean attribute creates a search field that doesn’t have an associated label. See Using Lookup to Find and Autofill an Address for more information.

You can also use custom labels that display translated values. For more information, see Access Labels.

We recommend that you provide a label even when you provide placeholder text for an address field. Without field labels, users can lose context when the placeholder text disappears as they type in the field.

Specify placeholder text to give users a hint about the content they’re expected to enter in the field. Avoid repeating the field label in the placeholder for better accessibility. Consider the width of your address field as the placeholder text is cut off if it’s too long, especially on mobile devices.

Include an optional placeholder for each field that you’re using, with these attributes.

• address-lookup-placeholder
• street-placeholder
• city-placeholder
• province-placeholder
• country-placeholder
• postal-code-placeholder

Use a combination of the variant and class attributes to customize the address fields.

Use the variant attribute with one of these values to apply different label positioning.

• label-hidden hides the compound field label but make it available to assistive technology. This variant does not hide the constituent field labels.
• label-inline horizontally aligns the compound field label and address fields.
• label-stacked places the label above the address fields.
• standard is the default value, which displays the label above the address fields.

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds padding on top of address fields using an SLDS class.

1<lightning-input-address
2    class="slds-p-top_small"
3    address-label="Address"
4    street-label="Street"
5    city-label="City"
6    country-label="Country"
7    province-label="Province"
8    postal-code-label="PostalCode"
9>
10</lightning-input-address>

The Street field renders a textarea and the other fields render input fields.

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Using show-address-lookup isn’t supported in Experience Builder sites, Lightning Out, Lightning Components for Visualforce, and standalone apps.

When working with address fields such as with the MailingAddress field on Salesforce records, consider using the record form components. The lightning-record-form, lightning-record-view-form, and lightning-record-edit-form components provide a form-based UI that’s metadata-driven. The components are automatically wired up to your record data, labels, and field-level help text. For more information, see Work with Records Using Base Components.

To create your own custom UI to work with Salesforce records, use lightning-input-address with the lightning/ui*Api wire adapters and functions, such as getRecord and updateRecord. For more information, see Use the Wire Service with Base Components.

To disable the fields so that users cannot interact with it, use the disabled attribute. If you want to prevent users from interacting with the country field only, disable it using the country-disabled attribute.

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 address. To hide the compound field label from view and make it available to assistive technology, use the label-hidden variant. This variant keeps the constituent field labels in view.

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

change

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

The change event returns the following parameters.

The change event properties are as follows.

Object Reference for the Salesforce Platform: Field Types