Input Address

lightning-input-address

Represents an address compound field.

For Use In

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

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

:::::tab

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

:::::

:::::tab

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.

<template>
    <div>
        <lightning-input-address
            address-label="Address"
            street-label="Street"
            city-label="City"
            country-label="Country"
            province-label="State"
            postal-code-label="PostalCode"
            street="1 Market St."
            city="San Francisco"
            country="US"
            province="CA"
            postal-code="94105"
            field-level-help="Enter your billing address"
        >
        </lightning-input-address>
    </div>
</template>

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

<p>You are located in: {city}</p>
    <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="PostalCode"
        city={city}
        onchange={handleChange} ></lightning-input-address>

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

import { LightningElement } from "lwc";

export default class AddressCityExample extends LightningElement {
  city = "San Francisco";

  handleChange(event) {
    this.city = event.target.city;
  }
}

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

Design

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.

Create Dropdown Menus for Country and Province

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.

<template>
    <div>
        <lightning-input-address
            address-label="Address"
            street-label="Street"
            city-label="City"
            country-label="Country"
            province-label="Province/State"
            postal-code-label="PostalCode"
            street="1 Market St."
            city="San Francisco"
            province="CA"
            country="US"
            country-options={getCountryOptions}
            province-options={getProvinceOptions}
            postal-code="94105"
            required
            onchange={handleChange}
        >
        </lightning-input-address>
    </div>
</template>

JavaScript file:

import { LightningElement } from "lwc";

export default class DemoInputAddress extends LightningElement {
  provinceOptions = [
    { label: "California", value: "CA" },
    { label: "Texas", value: "TX" },
    { label: "Washington", value: "WA" },
  ];

  countryOptions = [
    { label: "United States", value: "US" },
    { label: "Japan", value: "JP" },
    { label: "China", value: "CN" },
  ];

  get getProvinceOptions() {
    return this.countryProvinceMap[this._country];
  }
  get getCountryOptions() {
    return this.countryOptions;
  }

  handleChange(event) {
    this._country = event.detail.country;
  }
}

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.

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

The locale also determines which constituent fields are required. For example, the province (state) field is required with the en-US locale, but it isn't required with the fr-FR locale. The selected country value doesn't change the required fields. To apply consistent validation regardless of the user's locale, set the locale attribute explicitly instead of relying on the org's locale setting.

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

<template>
    <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"
        locale="en-US"></lightning-input-address>
</template>

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

<template>
    <h2>User's locale: {userLocale}</h2>
    <!--No locale specified on lightning-input-address -->
    <lightning-input-address
        lwc:ref="address"
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"></lightning-input-address>
</template>

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

import { LightningElement } from "lwc";

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

  renderedCallback() {
    this.userLocale = this.refs.address.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.

Hide the Province Field

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.

<template>
     <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"
        locale="fr-FR"
        hide-province
    ></lightning-input-address>
</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.

Use Lookup to Find and Autofill an Address

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.

<template>
    <lightning-input-address
        show-address-lookup
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="State"
        postal-code-label="Zip Code"
        street="1 Market St."
        city="San Francisco"
        country="US"
        province="CA"
    >
    </lightning-input-address>
</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.

Filter Address Lookup Based on Country Options

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.

<template>
    <lightning-input-address
        show-address-lookup
        address-label="Address"
        street-label="Street"
        city-label="City"
        province-label="State"
        country-label="Country"
        postal-code-label="Zip Code"
        country-lookup-filter={countries}
    >
    </lightning-input-address>
</template>

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

import { LightningElement } from "lwc";

export default class CountryFilterExample extends LightningElement {
  countries = ["AU", "GB", "JP"];
}

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

important: Using an invalid two-letter country code in the array prevents the Google Maps Places API from returning results and may trigger console errors. If the array contains a country code longer than two characters or exceeds the five-country filter limit, the component defaults to using no filter. Additionally, if a non-array value is passed to the attribute, the component also defaults to using no filter.

Use Compact Address Fields

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.

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

Use the Compact Address Fields with Address Lookup

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.

<lightning-input-address
    show-address-lookup
    show-compact-address
    address-label="Address"
    street-label="Street Line 1"
    city-label="City"
    country-label="Country"
    province-label="Province"
    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.

Use the Subpremise Field with Address Lookup

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.

<lightning-input-address
    show-address-lookup
    show-compact-address
    address-label="Address"
    street-label="Street Line 1"
    subpremise-label="Street Line 2"
    city-label="City"
    country-label="Country"
    province-label="Province"
    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.

Validate Required Fields

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.

    handleClick(e) {
        const address =
            this.template.querySelector('lightning-input-address');
        const isValid = address.checkValidity();
        if(isValid) {
            alert("Creating a new address");
        } else {
            alert("Complete all address fields");
        }
    }

note: The locale determines which fields are required. The country you select doesn't change the required fields. See Use the Locale Information.

Work with Labels and Placeholders

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

Component Styling

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

Variants

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.

Utility Classes

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.

<lightning-input-address
    class="slds-p-top_small"
    address-label="Address"
    street-label="Street"
    city-label="City"
    country-label="Country"
    province-label="Province"
    postal-code-label="PostalCode"
>
</lightning-input-address>

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

Styling Hooks

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.

Usage Considerations

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.

Accessibility

For accessibility, provide a text label using the label attributes. When you use address-label, street-label, city-label, and so on, the component generates the corresponding <label> elements and automatically binds them to their internal inputs using the correct for and id relations.

The address-label is the compound field label that provides the text for the <legend> element on the field set. To hide the compound field label from view and make it available to assistive technology, use the label-hidden variant.

Each constituent field corresponds to a label, such as street-label and city-label. The label-hidden variant has no effect on the labels on the constituent fields. If you use label-hidden, the constituent field labels remain visible. If you use show-address-lookup to display an address lookup field, the "Search Address" label also continues to be visible.

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

To use the keyboard to move focus through each constituent address field, use the Tab and Shift + Tab keys. If you configure the province-options or country-options attributes, use arrow keys to navigate options and use Enter or Space to select an option.

When you use show-address-lookup, a search field is shown to provide lookup functionality by using Google Maps Places API. The search dropdown follows accessible combobox patterns. As search results appear, screen readers announce the dynamic changes, and you can navigate the address suggestions using the keyboard.

When an address field is updated via the lookup, a status message that includes the address-label is announced by screen readers in this format:

{your_address_label} updated for country {your_country}

For example, if the address-label value is Billing Address and the country is United States, the status message reads:

Billing Address updated for country United States

Custom Events

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.

See Also

Object Reference for the Salesforce Platform: Field Types

:::::

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

:::::

::::::