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.

Examples

Mailing address

Mailing address - Military base

Address confirmation

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)
• 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 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 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.
• 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 VA.gov profile. If an address addition or change will not update the user’s VA.gov 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.

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

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

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

Military post office

Hint text: None

Error type: No entry

Error message: Select a type of post office: APO, FPO, or DPO

Overseas "state" abbreviation

Hint text: None

Error type: No entry

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