Help users to…

Update prefilled information

Usage

When to use this pattern

When you prefill the user’s information into an application, form, or other online tool. This pattern helps users filling out a form or tool understand how they can update their prefilled information, including sensitive information that they can’t update online. This pattern also informs users where we’ll save their changes—either only to the specific form or tool, or to the form or tool and their profile. The related Help users to know when their information is prefilled pattern has guidance on how to display the prefilled information.

When not to use this pattern

• When you don’t prefill the user’s information.
• For unauthenticated users. Users who aren’t signed in shouldn’t have their information prefilled when they interact with an application, or be able to update prefilled information. But, when forms don’t require users to be signed in, they should see an informational alert describing benefits to signing in. Check the unauthenticated intro page alert within the Help users to know when their information is prefilled pattern.

When to use caution

• When the user can’t update their information online, but can update another way. This pattern accounts for cases when the user needs to call VA or take a different step to change certain information, such as their name and Social Security number. You’ll need to confirm that you’re giving the correct instructions for changing that specific information.
• When the user can’t update their information at all. If your form prefills information that the user can’t change through any means, you’ll need to explain that directly.

How to design and build

Anatomy or layout details

This pattern involves these types of pages found in VA.gov forms:

• Prefilled information the user cannot update: This is usually personal information like name, date of birth, and Social Security number.
• Prefilled information the user can update: This can be many different types of information, like email addresses and mailing addresses, that the user can update directly on the screen where we display it.

Refer to the related Help users to know when their information is prefilled pattern for guidance on helping users know when their information is prefilled.

Prefilled information the user can’t update

Here’s how to communicate that users can’t update certain information online:

• Omit the edit link in the Card component with uneditable information.
• Include instructions for how to update uneditable information. Under the Card with the uneditable information, display a note starting with the bolded word “Note:” followed by directions to help users find out how to update this information by phone or another way. These directions will vary by form or type of information. You’ll need to confirm that the directions are accurate for updating that specific type of information. See the Content considerations section on this page for more guidance.

Prefilled information the user can update

Here’s how to communicate that users can update certain information online:

Display editable prefilled information in a Card - status with an edit link. Display prefilled information in a Card - status with a link to edit the information. This information may include contact information, such as phone number, email address, or mailing address.

When the user updates this information, there are two potential pathways for saving their changes.

If we automatically save changes to the user’s profile

In most cases, when users update information that can be edited in their profile, the changes should be saved to both the form or tool and the profile. An Alert - informational will indicate where we’ll save the changes.

For developer documentation on saving information changes to the profile, consult the prefill pattern README.

If address changes save to the profile, they apply everywhere

Let users know when updating their address in one place will update it everywhere. When an address change is saved to a user’s profile, either automatically or because the user opted in, it updates all VA accounts and records that use it, not just the current form or page.

If we let the user opt in to saving changes to their mailing address

For mailing addresses only, users may need the choice to opt in to saving their changes to their profile. Instead of displaying an informational alert at the top of the page, display a question at the bottom of the page asking the user if they also want to update their profile. This gives users control over whether a mailing address change on this form or tool also updates their VA.gov profile.

Note: Phone number and email address updates always save to both the form and the user’s profile. Only mailing address updates can be saved to the form only.

Consider using this opt-in variation for mailing addresses that may change frequently. For example, when reordering medical supplies, users may want to provide a temporary mailing address. But they may not want this temporary mailing address to save to their profile.

After the mailing address fields the person is updating, include this question:

Do you want to update this information in your profile? (*Required)

Hint text: If you select “yes,” we’ll update this information across multiple VA benefits and services. [LINK: Learn more about changing your address in your profile (opens in a new tab)]

The radio options should be:

• Yes, also update my profile
• No, only update this [form, application, claim, tool]

Address validation on submit

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:

Address changes while a form is in progress

The 4 paths above happen when a user submits an address. Separately, a user’s address on their VA.gov profile can change while they have a form, application, or claim already in progress. Depending on the form, this shows up one of two ways: an alert that the addresses don’t match, or the form address updating automatically to match the profile.

Address mismatch on in-progress forms

If a user changes their address in their VA.gov profile while they have an in-progress form, application, or claim, the saved address on that form won’t automatically update to match. When the user returns to the review page for that form, they see an alert letting them know the addresses don’t match, so they 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:

If we let the user choose which piece of information they want to use for the form

In certain cases, users may need to choose which piece of information they want to use on the form. An example of this is if you prefill the user’s mobile and home telephone numbers, but the form only asks for a primary phone number. In these instances, after the user confirms their prefilled information, display a question asking the user which information they want to use on the form.

Prefilled information that is missing and required

There may be instances where some information that would usually be prefilled is missing from the database, but is also required by the form itself. In those instances, we show a Card - status that uses a Status tag to indicate that the information is missing. The card will also have the word “(*Required)” next to the field heading text to indicate the user needs to provide that information. The secondary action link for this card would say “Add [item]” rather than “Edit [item]”.

If the user does not provide the required missing information and selects the “Continue” button to try and move forward, they’ll get the same page with that Card - status in an error state and red error text telling them what information they need to provide. Once they select “Add” and provide the information on an edit page, they will be redirected back to this screen and can continue through the form.

Communicate when and where we’ll save updates to prefilled information

Inform users where we saved the changes. Display an Alert - success informing the user “We’ve saved these changes to this form and your profile.” or “We’ve saved these changes to this form only.” Place this alert at the top of the page, below the stepper. Use an Alert if the user made the changes on a form step page. Use an Alert - success - slim if the user made the changes on the final review page.

Components used in this pattern

• Alert
• Card
• Card - status
• Link
• Radio button

Examples

Note after uneditable prefilled information

Explain the steps the user needs to take to update this information. These instructions will vary by form. For some forms, the user will need to call us to find out how to update this information. The specific number to call will vary by form.

Alert informing the user we’ll save changes to their profile

Inform the user that their changes will save to their profile before they make the changes. If your form lets users opt in to saving mailing address changes to their profile instead, use a Radio button to ask a question instead (example in the Radio button section).

Success alert

Inform users that we saved their change to the form and their profile. If we only saved the change to the form, the alert should read “We saved these changes to this form only.”

If the user made the change on the final review page, display the Alert - success - slim on the review page, immediately after the header of the section where they made the change.

Radio button

In cases where the mailing address might change frequently (like a temporary mailing address), let the user opt in to saving their changes to their profile by asking a question. Inform the user of the implications of this decision.

Example within a mock form

An example of the prefill pattern can be found in the Forms library mock form on staging. Sign in with any staging user.

Code usage

• Address validation pattern README has implementation instructions for address validation.
• Code for the prefill pattern can be found in the Forms library.

Content considerations

Directions for updating uneditable information

Directions for updating information vary by form, benefit type, and type of information. You must confirm with subject matter experts that your instructions are accurate for the way your specific form populates information and how to update it. And you must confirm with the call center that they will be able to either update the information directly. If they can’t update the information directly, give the person instructions for how to update the information.

Here’s an example that tells people to call the VA benefits hotline:

Note: To protect your personal information, we don’t allow online changes to your name, date of birth, or Social Security number. If you need to change this information, call us at 800-827-1000 (TTY: 711). We’re here Monday through Friday, 8:00 a.m. to 9:00 p.m. ET.

Find more detailed instructions for how to change your legal name (opens in new tab)

Error messages

If the information can’t be saved onto profile, but can be used for the form

Warning alert: We can’t update your information in your profile. But you can continue filling out this [form/application] and update your profile information later.

If the information can’t be saved for profile or for the form

Error alert: We can’t save your current information. Try again later.

If the required information is missing

Inline error message: You must add your [missing content].

Accessibility considerations

• Focus should return to the success alert when an item has been updated.

Research findings

The Authenticated Experience Design Patterns team conducted user research in late 2024 about how users prefer to see their editable and uneditable information, and how they prefer to be informed about how to edit it. Most participants want updates to save to their profile, but some also want the ability to choose where the updates save, in the case that they are using a temporary address or other temporary situation.

This pattern would benefit from additional research. Specifically for the scenario where there is missing and required prefilled information, research to understand if the solution suggested here is effective and understandable for users would be helpful in strengthening this pattern guidance.