Input Address

A lightning-input-address 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 country-options and province-options 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.

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

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

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

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.

JavaScript file:

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

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

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

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.

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.

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.

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.

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

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.

Using show-address-lookup is not supported in Experience Builder sites, Lightning Out, Lightning Components for Visualforce, and standalone apps. While it may work, these targets are not optimized and not officially supported.

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.

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.

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.

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.

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

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

lightning-input-address implements the form element address blueprint in the Salesforce Lightning Design System (SLDS).

You can 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.

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

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Input: Styling Hooks Overview and Textarea: Styling Hooks Overview for documentation on component-specific hooks for this component.

Using show-address-lookup 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-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.