Ask users for…

Addresses

Usage

When to use this pattern

• Asking for an address. For example, the address for a military base, home, or mailing address.

Address validation requirements

• Veteran mailing addresses must always be validated. Since VA correspondence and benefits depend on an accurate mailing address, always validate a Veteran’s mailing address against USPS.
• Other mailing addresses should be validated. For mailing addresses that don’t belong to the Veteran (such as a third-party or dependent’s address), validate the address whenever possible.
• Addresses collected only for record-keeping purposes don’t need to be validated. If an address is stored for reference and isn’t used for mailing or benefits delivery, validation isn’t required.

Examples

Mailing address

Include a checkbox labeled “I live on a U.S. military base outside of the United States” with the mailing address fields. When checked, the Country field is set to United States and becomes read-only, and the City and State/province/region fields are replaced with Military post office and Overseas “state” abbreviation options to match standard military address formatting.

Note: This example is for illustration only. For implementation-ready code, see Code usage.

How to design and build

Layout details

Here is the content structure for asking a user for an address:

• Header - Mailing or Home Address
• Relevant information regarding this form and the user’s address (if applicable)
• Checkbox for military address (if applicable)
• Details component (if applicable)
• Country select box
• Street address text input
• Street address line 2 text input
• Street address line 3 text input (if applicable)
• City text input
• State/Province/Region text field or select box (dependent on Country selection)
• Postal code text input
• Radio button component for mailing address same as home address (if applicable; this is on mailing address page only)

How this pattern works

Single address details

• If required, include a checkbox for United States military base address. Under the Details component, there should be an explanation:

The United States is automatically chosen as your country if you live on a military base outside of the country.

• If asking for only one address on a form, be clear which address (mailing or home) you’re asking for. We recommend asking for a mailing address if you need to only ask for one address.
• Street address Line 3 can be omitted. Sometimes partner databases do not support a third line of address.
• State/Province/Region field type is determined by selected Country. The State/Province/Region input field changes from a text-input to a select menu based on the country entered. When you select the United States, Canada, or Mexico, the input changes to a select menu and displays the appropriate options for the selected country.

Multiple addresses: Mailing and Home addresses details

Follow this guidance when asking for both mailing and home addresses. In some forms, we ask for both addresses because some Veterans live in different homes depending on the time of year.

• The mailing address always comes before home address. We ask for a mailing address before home address because the majority of VA’s correspondence is over mail.
• On the mailing address form, ask users if the home address is the same as the mailing address. If the user chooses “Yes”, they can skip the home address form.
• Indicate to users whether an update in this form will update their profile home or mailing address. If an address addition or change will not update the user’s profile, then use the text “We’ve made these changes to only this form.” Refer to the Help users to update prefilled information pattern for information on how to communicate that an update will be reflected in their profile.

How address validation is implemented

This validation happens through one of two integration points, depending on how the address was entered, but produces the same experience either way:

• A newly entered address (not prefilled) is validated using the standalone address validation pattern, a reusable form page placed immediately after the address page.
• A prefilled mailing address that a user edits is validated through the VA Profile “edit mailing address” flow instead, reusing the same USPS decision policy directly. Forms that use the prefill contact info pattern shouldn’t also add the standalone address validation page, since that would prompt the user to confirm their address twice.

See the address validation pattern README for implementation details, decision policy, and known limitations.

There are 4 possible paths after a user submits their address

1. Happy path: USPS confirms the entered address exactly, and the user continues.
2. Suggested address path: USPS can validate the address, but suggests a different formatting or unit information than what the user entered. The user chooses which version to save.
3. No usable address found path: USPS can’t find a matching address (or the validation service is unavailable). The user sees a warning and can fix the address they entered or continue with it as-is. Validation never blocks the user from moving forward.
4. Undeliverable address path: The address was already validated by USPS, but mail sent to it is later returned to sender. This can happen if the person no longer lives at that address. VA.gov flags the address and lets the user know they may need to update it.

Suggested address

When USPS suggests a different address than what the user entered, the user sees a confirmation screen and chooses which version to save:

For implementation instructions, see the address validation pattern README.

No usable address found

When USPS can’t find a matching address (or the validation service is unavailable), the user sees a warning but isn’t blocked from continuing. They can go back and fix the address, or continue with what they entered:

Undeliverable address

When mail sent to a saved address is later returned to sender, the user sees a warning the next time they visit a form that uses that address:

Profile and form addresses

The 4 paths above happen when a user submits an address. Separately, the address saved on a form can differ from the address in the user’s VA.gov profile. Depending on how the form handles addresses, the user may see an alert that the addresses don’t match, or the form address may update automatically to match the profile.

Address mismatch on review pages

When a form uses the Addresses pattern without prefill, the user enters their address directly in the form. The form doesn’t compare that address with the address in the user’s VA.gov profile when they enter it, so the two addresses may differ. On the review page, compare the addresses and show a warning alert if they differ so the user can check which one is correct before submitting:

Address updated automatically

Sometimes an address mismatch doesn’t happen at all: if a user changes their address in their VA.gov profile while they have an in-progress form, some forms automatically update the saved address on that form to match the profile, instead of showing a mismatch alert. When this happens, the user sees an informational alert letting them know their address was updated for them:

Prefill information details

Inform users when prefilling information from their profile. When information is pre-populated into a form we notify users using the Know when their information is prefilled pattern.

Components used in this pattern

• Checkbox
• Prefill, when profile information is pre-populated into an address.
• Select
• Text input

Page templates available for this pattern

Use the VADS templates (Patterns & Forms) for Addresses in Figma.

Code usage

• Address validation pattern README has implementation instructions for address validation.
• addressPattern is a web-component pattern available in the Forms library.

Content considerations

• If you need to display an address after it has been collected, then follow content style guidelines on addresses.

Labels, error messages, and hint text

Mailing address

Hint text: None

Home address

Hint text: None

Country

Hint text: None

Error type: No selection

Error message: Select a country

Street address

Hint text: None

Error type: No entry

Error message: Enter a street address

Street address line 2

Hint text: None

Street address line 3

Hint text: None

City

Hint text: None

Error type: No entry

Error message: Enter a city

State, province, or region

Hint text: None

Error type: Default

Error message: Enter a valid State, Province, or Region

Error type 2: Canada

Error message 2: Select a Province or Territory

Error type 3: Mexico

Error message 3: Select a State

Postal code

Hint text: None

Error type: No entry and country is unknown

Error message: Enter a postal code

Error type 2: No entry and user lives outside of the U.S.

Error message 2: Enter a postal code that meets your country’s requirements. If your country doesn’t require a postal code, enter NA.

Error type 3: No entry and user lives in the U.S.

Error message 3: Enter a valid 5-digit zip code

Military post office

Hint text: None

Error type: No entry

Error message: If your mailing address is an APO/FPO/DPO address, enter the postal code for the military base.

Overseas "state" abbreviation

Hint text: None

Error type: No entry

Error message: Select an abbreviation: AA, AE, or AP

Adoption