---
schema_version: "1"
id: 17bbb493275112015201c8bc7c806374faeb524a44c99358ce46a529dae9b0e6
title: Input Address
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/inputAddress/lightning-input-address.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-address.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: cad89fd9a9394d3de49c0223f7589c05d505d5da2b1ba8513e5f7beb8c4fa93e
products:
  - Lightning Component Reference
---

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

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

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

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

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

```js
import { LightningElement } from "lwc";

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

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

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

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

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

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

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

JavaScript file:

```javascript
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](https://help.salesforce.com/articleView?id=admin_state_country_picklists_overview.htm) in Salesforce Help and [getPicklistValues](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values) 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 &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 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)](https://help.salesforce.com/s/articleView?id=xcloud.admin_supported_locales.htm).

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

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

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

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

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

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

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.

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

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

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

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

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

```javascript
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](https://developers.google.com/public-data/docs/canonical/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.

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

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

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

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.

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

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.

```javascript
    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](#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](#use-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](https://developer.salesforce.com/docs/platform/lwc/guide/create-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](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

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

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

The Street field renders a [textarea](https://v1.lightningdesignsystem.com/components/textarea) and the other fields render [input](https://v1.lightningdesignsystem.com/components/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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) 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](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro).

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](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-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](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) 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.

| Parameter  | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| street     | string | The number and name of street.     |
| city       | string | The name of the city.              |
| province   | string | The name of the province/state.    |
| country    | string | The name of the country.           |
| postalCode | string | The postal code for the address.   |
| 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

[_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="inputAddress" model="lwc" namespace="lightning"}

:::::

::::::