Use an address component to collect a postal address as a structured set of fields. It supports manual entry and address autocomplete. Choose the pattern that works for all the people who need to use the service, including those with an address that cannot be found by a lookup.

Choose an address-entry pattern

flowchart TD
  A[Who will use the service?] --> B{Can addresses use different national formats?}
  B -- Yes --> C[Start with manual entry or global autocomplete]
  B -- No --> D{Is a reliable local lookup available?}
  D -- Yes --> E[Use lookup with manual fallback]
  D -- No --> F[Use manual entry]
  C --> G[Test unfamiliar, incomplete and not-found addresses]
  E --> G
  F --> G

Autocomplete and local lookup are mutually exclusive configuration patterns. Choose one, or use manual entry; do not try to combine them.

Configure manual entry for real addresses

Manual entry can include address lines, locality, administrative area, postal code and country. The first address line is always present and required. Configure the remaining fields to match the information your service genuinely needs.

For a service used internationally, include country and use neutral labels such as:

• Address line 1
• Address line 2 (optional)
• City or locality
• State, province or region (optional)
• Postal or ZIP code (optional where appropriate)
• Country

Do not force every address into one country’s conventions. In particular, make postal-code validation flexible unless the service requirement is explicitly limited to one local format.

Mark a field required only when the service cannot process the address without it. A country may be essential for cross-border delivery, while a region may not be meaningful for every address.

Use autocomplete as assistance, not a gate

Address autocomplete can help people find an address and populate the component fields. It can be filtered to a country or region, or searched more broadly.

The person must still be able to enter or correct the address manually. Lookups can be incomplete, delayed, unavailable, or unable to represent new buildings, rural locations and non-standard addresses.

When configuring autocomplete, review how source values map to address lines, locality, region, postal code and country. Do not assume source data uses the same address order or terminology as your service. Test sample addresses from every region you expect to support.

Important: Treat an address returned by a lookup as a suggestion. A person should be able to correct a line, add an apartment or building name, or use manual entry when the result is wrong.

Write helpful labels and hints

Use the component label to explain why you need the address, such as “What is the address where the equipment will be delivered?” Use hint text to state any scope or delivery requirement.

Avoid a generic label such as “Address” when the service collects more than one address. Distinguish them clearly, for example:

• Home address
• Correspondence address
• Delivery address
• Address of the property you are reporting

On review pages, provide a short label where needed so the address can be distinguished from other address components. Keep the person-facing review value readable rather than exposing separate field identifiers.

Pre-populate and reset safely

An address can be pre-populated from earlier journey data or a trusted integration. Let a person change a suggested address unless a genuine policy reason prevents it. If another answer means a pre-filled address is no longer relevant, reset it deliberately and make the relationship clear.

Test a new journey, a returned page, a changed pre-filled address, an upstream change and a resumed draft. Check that every address line persists and returns in the correct field.

Privacy and accuracy

An address is personal information. Collect only the parts you need, tell people why you need them where that is not obvious, and do not display more detail than necessary in summaries or messages.

If an address is used by actions or integrations, test the exact structured output before deployment. A correctly displayed address can still be mapped incorrectly downstream.

Testing checklist

• Manual entry works without any lookup service.
• A lookup result can be corrected and replaced with manual entry.
• The component accepts the address formats used by the intended audience.
• Required lines, postal code and country match the real processing need.
• Autocomplete mapping places source values in the correct address fields.
• An address with an apartment, building name or non-standard layout remains understandable.
• Review, actions and templates display the address appropriately.
• Pre-population and reset behaviour retain or clear every line as intended.

Related guidance

• Shared component settings
• Text components
• Connect data, files and SharePoint
• Design accessible services