Addresses

Use: Deployed

Follow this pattern to ask a user for an address.

Usage

When to use this pattern

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

Examples

Mailing address

View an example

Mailing address - Military base

An example of a mailing address form that includes the option for a military base. — Example of a form collecting a mailing address on a military base.

View an example

Address confirmation

An Alert in a form flow that warns the user that the address they entered could not be found in U.S. Postal Service data. — Example of an alert warning a user that the address they entered does not match U.S. Postal service data and providing a way for them to correct their address or use the corrected address from the Postal service.

How to design and build

Layout details

Single address layout

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

Checkbox for military address (if applicable)
Additional info 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 select box
Postal code text input

Multiple addresses layout

Here is the content structure for asking a user for multiple addresses:

Header - Mailing or Home Address
Relevant information regarding this form and the user’s address (if applicable)
Checkbox for military address (if applicable)
Additional info 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 select box
Postal code text input
Radio button component for mailing address same as home address (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 additional information 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.

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 VA.gov profile. If an address addition or change will not update the user’s VA.gov profile then use the text “Any updates you make here to your address will only apply to this application.” Refer to the Help users to know how their information is updated pattern for information on how to communicate that an update will be reflected in their profile.

Address confirmation details

Check addresses against USPS data. Confirm the user’s address against U.S. Postal Service data and warn the user with a warning Alert when the address they entered is potentially incorrect.
Provide a way to edit or use the potentially incorrect address. Provide a link to edit the address so that a user can correct any potential errors. Also provide a way for the user to override the address check and continue with the address they provided.

Prefill information details

Inform users when prefilling information from VA.gov profile. When information is pre-populated into a form we notify users using the Prefill component

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

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

Physical 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; Label variation: Apartment or unit number

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: No entry and user lives in the U.S. (If user lives outside of the U.S., this field should remain optional.); Error message: Select a state or territory

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- or 9-digit zip code

APO, FPO, or DPO: Hint text: None; Error type: No entry and user has selected military base checkbox; Error message: Select a type of post office: APO, FPO, or DPO