Input Address

A lightning:inputAddress component creates a compound field that includes the following constituent fields.

• Street
• City
• Province
• Country
• Postal code

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

This example creates an address compound field with attributes to specify values for the constituent fields. The initial values are set directly with the attributes.

1<aura:component>
2  <div style="max-width: 400px;">
3    <lightning:inputAddress
4      aura:id="myaddress"
5      addressLabel="Address"
6      streetLabel="Street"
7      cityLabel="City"
8      countryLabel="Country"
9      provinceLabel="State"
10      postalCodeLabel="PostalCode"
11      street="1 Market St."
12      city="San Francisco"
13      country="US"
14      province="CA"
15      postalCode="94105"
16      required="true"
17      fieldLevelHelp="Enter your billing address"
18    />
19  </div>
20</aura:component>

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

This example adds a custom attribute previousCountry that’s used to check if the country is changed.

1<aura:component>
2  <aura:attribute
3    name="provinceOptions"
4    type="List"
5    default="[
6        {'label': 'California', 'value': 'CA'},
7        {'label': 'Texas', 'value': 'TX'},
8        {'label': 'Washington', 'value': 'WA'},
9    ]"
10  />
11  <aura:attribute
12    name="countryOptions"
13    type="List"
14    default="[
15        {'label': 'United States', 'value': 'US'},
16        {'label': 'Japan', 'value': 'JP'},
17        {'label': 'China', 'value': 'CN'},
18    ]"
19  />
20  <aura:attribute name="previousCountry" type="String" />
21
22  <div style="max-width: 400px;">
23    <lightning:inputAddress
24      aura:id="myaddress"
25      addressLabel="Address"
26      streetLabel="Street"
27      cityLabel="City"
28      countryLabel="Country"
29      provinceLabel="Province/State"
30      postalCodeLabel="PostalCode"
31      street="1 Market St."
32      city="San Francisco"
33      country="US"
34      countryOptions="{! v.countryOptions }"
35      provinceOptions="{! v.provinceOptions }"
36      postalCode="94105"
37      onchange="{! c.updateProvinces }"
38    />
39  </div>
40</aura:component>

The client-side controller and helper Javascript file initialize the picklist values. The updateProvinces function is called when you change any address field.

The province options update only when you select a different country. The custom attribute previousCountry value is compared to the value of country before updating provinceOptions. This improves performance. Without the comparison, the provinceOptions picklist is always updated when you change a field in the address, even if you don’t change the country selection.

The client-side controller:

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.countryOptions", helper.getCountryOptions());
4    cmp.set("v.provinceOptions", helper.getProvinceOptions(cmp.get("v.country")));
5  },
6  updateProvinces: function (cmp, event, helper) {
7    if (cmp.get("v.previousCountry") !== cmp.get("v.country")) {
8      cmp.set("v.provinceOptions", helper.getProvinceOptions(cmp.get("v.country")));
9    }
10    cmp.set("v.previousCountry", cmp.get("v.country"));
11  },
12});

The helper Javascript file:

1({
2  countryProvinceMap: {
3    US: [
4      { label: "California", value: "CA" },
5      { label: "Texas", value: "TX" },
6      { label: "Washington", value: "WA" },
7    ],
8    CN: [
9      { label: "GuangDong", value: "GD" },
10      { label: "GuangXi", value: "GX" },
11      { label: "Sichuan", value: "SC" },
12    ],
13    VA: [],
14  },
15  countryOptions: [
16    { label: "United States", value: "US" },
17    { label: "China", value: "CN" },
18    { label: "Vatican", value: "VA" },
19  ],
20  getProvinceOptions: function (country) {
21    return this.countryProvinceMap[country];
22  },
23  getCountryOptions: function () {
24    return this.countryOptions;
25  },
26});

Alternatively, you can enable state and country picklists in your org, and access the values through an Apex controller. For more information, see Let Users Select State and Country from Picklists in Salesforce Help.

In Lightning Experience, the locale value corresponds to the Locale field on the Language & Time Zone page in the user’s settings. For example, if you select “French (France)” in the Locale field, lightning:inputAddress uses fr-FR as the locale.

To override the locale on your user’s settings, provide your own locale value.

1<lightning:inputAddress>
2  addressLabel="Address" streetLabel="Street" cityLabel="City" countryLabel="Country"
3  provinceLabel="Province" postalCodeLabel="Postal Code" locale="en-US">
4</lightning:inputAddress>

In this example, the {!$Locale.userLocaleLang} global value provider returns fr and the {!$Locale.userLocaleCountry} global value provider returns FR. The lightning:inputAddress component uses the en-US locale.

For more information, see $Locale in the Lightning Aura Components Developer Guide.

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, set the hideProvince attribute to true. For example, you can use hideProvince when the locale is fr-FR or zh-CN.

1<lightning:inputAddress
2  addressLabel="Address"
3  streetLabel="Street"
4  cityLabel="City"
5  countryLabel="Country"
6  provinceLabel="Province"
7  postalCodeLabel="Postal Code"
8  locale="fr-FR"
9  hideProvince="true"
10>
11</lightning:inputAddress>

If you don’t provide a value for provinceLabel, the component renders with a province field without a label. Hide the field using hideProvince="true".

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

1<lightning:inputAddress
2  showAddressLookup="true"
3  addressLabel="Address"
4  streetLabel="Street"
5  cityLabel="City"
6  countryLabel="Country"
7  provinceLabel="State"
8  postalCodeLabel="Zip Code"
9  street="1 Market St."
10  city="San Francisco"
11  country="US"
12  province="CA"
13  postalCode="94105"
14/>

When you start typing an address in the lookup field, a dropdown appears with 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 countryLookupFilter attribute. Country codes are case-insensitive. You can specify a maximum of five country codes. Enable address lookup by including showAddressLookup.

1<aura:component>
2  <aura:attribute name="countries" type="List" default="['US', 'JP', 'CN']" />
3
4  <div style="max-width: 400px;">
5    <lightning:inputAddress
6      aura:id="myaddress"
7      addressLabel="Address"
8      streetLabel="Street"
9      cityLabel="City"
10      provinceLabel="State"
11      countryLabel="Country"
12      postalCodeLabel="Zip Code"
13      countryLookupFilter="{! v.countries }"
14      showAddressLookup="true"
15    />
16  </div>
17</aura:component>

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

If you pass in an invalid country code or more than five codes, Google Maps Places API produces console errors and returns no results.

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 showCompactAddress attribute. Use streetLabel to provide a label for the first line of address, and use subpremiseLabel for the second line of address. You can add supplementary information on this field, such as a building number or unit name.

1<lightning:inputAddress
2  showCompactAddress="true"
3  addressLabel="Address"
4  streetLabel="Street Line 1"
5  subpremiseLabel="Street Line 2"
6  cityLabel="City"
7  countryLabel="Country"
8  provinceLabel="Province"
9  postalCodeLabel="Postal Code"
10></lightning:inputAddress>

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

1<lightning:inputAddress
2  showAddressLookup="true"
3  showCompactAddress="true"
4  addressLabel="Address"
5  streetLabel="Street Line 1"
6  cityLabel="City"
7  countryLabel="Country"
8  provinceLabel="Province"
9  postalCodeLabel="Postal Code"
10></lightning:inputAddress>

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 subpremiseLabel 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 streetLabel. The subpremise field doesn’t require a value for submission.

1<lightning:inputAddress
2  showAddressLookup="true"
3  showCompactAddress="true"
4  addressLabel="Address"
5  streetLabel="Street Line 1"
6  subpremiseLabel="Street Line 2"
7  cityLabel="City"
8  countryLabel="Country"
9  provinceLabel="Province"
10  postalCodeLabel="Postal Code"
11></lightning:inputAddress>

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="true", 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 controller action. You can display the error message when a user clicks the button without providing a value on a field.

1({
2  handleClick: function (cmp, event) {
3    var address = cmp.find("myaddress");
4    var isValid = address.checkValidity();
5    if (isValid) {
6      alert("Creating new address");
7    } else {
8      address.showHelpMessageIfInvalid();
9    }
10  },
11});

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.

• addressLabel
• streetLabel
• cityLabel
• provinceLabel
• countryLabel
• postalCodeLabel

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

Additionally, the showAddressLookup 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.

Your Salesforce locale setting determines the order and layout of the address fields by default. Use the locale attribute to override the default. Specify any locale code from the list of Supported Number, Name, and Address Formats (ICU) .

You can also use custom labels that display translated values. For more information, see the Lightning Aura Components Developer Guide.

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 you’re using, with the following attributes.

• addressLookupPlaceholder
• streetPlaceholder
• cityPlaceholder
• provincePlaceholder
• countryPlaceholder
• postalCodePlaceholder

Using showAddressLookup is not 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:recordForm, lightning:recordViewForm, and lightning:recordEditForm 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 Lightning Data Service.

To create your own custom UI to work with Salesforce records, use lightning:inputAddress with the force:recordData component.

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