Ask users for…

Multiple responses

Also known as: List & Loop

Contributors

Jeana Clark (Ad Hoc)

Robert Hasselle (Oddball)

Robin Garrison (Ad Hoc)

Usage

When to use this pattern

• Collecting the same data in a series of questions. Forms will often collect the same information about 1 or more items. For example, personal information about a Veteran’s dependents. The paper form equivalent would be a table where each row is an item and the columns are the questions.
• Collecting many possible responses. Some questions can have an unknown amount of answers, such as “list all the cities and states you’ve lived within.” This pattern appears in forms when we don’t know how many responses to a question a user will provide, but we need to collect a number between 1 and “n,” where “n” is all possible responses. This pattern appears in both simple and complex ways.

When not to use this pattern

• Collecting a single, or limited, response. For questions in a form that only have one answer, such as “What is the city and state of your birth?”, use the Ask users for a single response pattern.
• Inconsistent questions being asked for each item. Don’t use this pattern if you’re asking different questions for each item. This pattern works best when you need the same information for every item.

How to design and build - Multi-page

Use this pattern when users need to add similar information multiple times, such as information about dependents. This method allows more table-like data to be collected following the One thing per page principle.

When to use the multi-page variation

• This is the default and preferred variation for multiple responses. This method is the most flexible of the variations of obtaining multiple responses because it can collect just one or multiple pieces of information across multiple pages. Thus it can collect a very limited set of data or complex details.

When to not use multi-page

• Most of the information being requested is already available. If we have most of the information being requested already then the “Add item” variation is preferred. If the information we have on file is contact information coming from VA.gov Profile then the “Contact information” variation is preferred.

Required vs Optional multi-page patterns

There are two types of multiple page patterns with slightly different user flows:

• Required Multi-page Pattern
  Use when at least one item for this step must be added.
• Optional Multi-page Pattern
  Use when the step is completely optional and users may or may not add items.

Required multi-page pattern user flow

The introduction page provides users with information about the next few screens. If there’s a limit to the maximum number of items, see the code & content considerations to customize the language.

The user proceeds into the questions flow. We recommend following the One thing per page pattern.

At any time in the questions flow a user can exit by clicking the Cancel adding this [thing] button. A modal appears to confirm their choice. If they confirm, any data they have entered is removed, and the user is returned to the Introduction page.

A summary page allows users to review what they’ve entered formatted as summary cards. If the user chooses to add another item, they return to the first question page to add the new item.

Clicking Edit puts the user into the “edit flow” and returns the user to the first question page. When entering the edit flow, the H3 of the pages are updated to include “Edit [previous h3 title]”. The fields should pre-populated with their previously supplied information. (Note: There is no Cancel button on this page during the editing process.) After editing items, the user returns to the summary page and an informational alert is shown confirming their item has been updated.

A user may choose to delete any of the summary cards. When clicking Delete, a modal appears asking them to confirm their choice. If they confirm, that card is removed from the page. If all cards are removed from the summary page, the user will then redirect to the first question page with a warning alert reminding the user at least one item is required.

Optional multi-page pattern user flow

The introduction page provides users with information about the next few screens and provides a Yes/No choice to provide additional information. If the user selects Yes they will proceed into the questions flow. If the user selects No, they proceed to the next step.

The user proceeds into the questions flow. We recommend following the One thing per page pattern.

At any time in the questions flow a user can exit by clicking the Cancel adding this [thing] button. A modal appears to confirm their choice. If they confirm, any data they have entered is removed, and the user is returned to the Introduction page.

A summary page allows users to review what they’ve entered formatted as summary cards. If the user chooses to add another item, they return to the first question page to add the new item.

Clicking Edit puts the user into the “edit flow” and returns the user to the first question page. When entering the edit flow, the H3 of the pages are updated to include “Edit [previous h3 title]”. The fields should pre-populated with their previously supplied information. (Note: There is no Cancel button on this page during the editing process.) After editing items, the user returns to the summary page and an informational alert is shown confirming their item has been updated.

A user may choose to delete any of the summary cards. When clicking Delete, a modal appears asking them to confirm their choice. If they confirm, that card is removed from the page. If all cards are removed from the summary page, the user is redirected to the Introduction page.

Code & content considerations

• Use the built in error and validation messages.
  • Successful editing of an item
  • Successful removal of an item
  • When the maximum number of items have been added
  • When all items in a required loop have been removed
  • When a user wants to cancel adding an item mid-flow
• Use the built in functionality for using the same word for adding an item on question pages, summary cards, and edit pages. For example:
  • Do you want to add another [dependent]?
  • Review your [dependents]
  • Remove a [dependent]
  • You have added the maximum number of [dependents]
• If at least one item is required, use hint text to let users know. The pattern must indicate to users that at least one item is required. If all items are removed, return users to the first page of the loop to gather information.
• If there are a maximum number of items, make this clear to the user. You can use hint text to do this. Also, after the user has entered the maximum number allowed the pattern removes the “add another” question, and displays a warning instructing the user that they have entered the maximum allowed and they can either edit, or remove a card if they need to add more information.

For more details

URL Guidance

When you design forms that collect several responses, make sure the URL shows which item the user is working on. Put the item’s position in the URL, like /dependents/0/name for the first dependent. Don’t use query parameters. This makes it easier for users to find, edit, and share links to specific items.

How we show “which item” in the URL

We include a folder-like path segment that holds the item’s position in the list for the current item. This is called the array index.

/<form-root>/<section>/<array-name>/<index>/<question-path>

• <index> is zero-based: the first item is /0/, the second is /1/, and so on. This matches how arrays work in code. It keeps routing logic simple and predictable.. Example:
  • First item: /app-name/dependents/0/name
  • Second item: /app-name/dependents/1/name

This structure lets the form deep-link to any item’s questions. It also simplifies ‘Back/Next’ behavior within the loop. It also aligns with our “ask for multiple responses” pattern guidance, which gathers the same fields for each item. Note: This creates two empty folders in the URL, which is different from VA’s URL standards.

Tip for labels: When showing labels to users, use the item’s name, like “Edit John Smith’s information,” not “Edit Dependent 1’s information.”

Why zero-based in the URL?

• Matches data structures: The system stores form data as arrays. Items are numbered 0, 1, 2….
• Reduces off-by-one bugs: Routes, validators, and UI state all point to the same index.
• Easier deep links and error recovery: a validation error can link directly to /…/2/… without translation.

URL structure examples

Collecting multiple employers

/app-name/employers/0/name-and-address  # First employer
/app-name/employers/0/dates
/app-name/employers/1/name-and-address  # Second employer
/app-name/employers/1/dates

Collecting multiple service periods

/app-name/service-history/0/branch-rank      # First service period
/app-name/service-history/0/start-end-date
/app-name/service-history/1/branch-rank      # Second service period
/app-name/service-history/1/start-end-date

Do’s and don’ts

Do

• Keep the item’s position in the list (not a query string) so each step is a clean, shareable route.
• Keep question paths stable (/name, /start-date) across items to enable reuse of the same screen for each index.
• Use this pattern anytime you “loop” a single-response screen across items.

Don’t

• Don’t encode the item’s position in the question path (e.g., avoid dependent-two-name).
• Don’t renumber the item’s position in the URL when items are re-ordered in the UI; treat the number as the item’s position in the current array at render time.
• Don’t refer to the arrays as <array-name> 1 in visual presentation.

Edge cases and tips

• Insertions and deletions: If a user deletes item 1, the remaining items will shift (2 becomes 1). That’s expected—routes always reflect the current state of the array. If you need stable IDs for analytics, store a separate per-item UUID in data. Keep the URL index for navigation.
• Validation links: Error summaries should link straight to the indexed route (for example, the second dependent’s name error links to /…/dependent/1/name), which takes users to the correct screen for that item in the loop.
• Accessibility notes: Because every looped screen is a normal single-response screen, follow the standard single-response accessibility guidance (clear page heading, field labeling, focus management). The pattern simply repeats those screens for each array index.

Accessibility considerations

On the summary page, ensure that the edit links and delete buttons have accessible text so that screen reader users understand what is being edited or deleted.

Examples in Production

How to design and build - Add item

This method shows all items on one page in a list with an “Add a new [item]” Link - Action (primary) at the bottom of the list that navigates the user to a new page to add the item.

• Items are displayed in a list with checkboxes for selecting items.
• The “Add a new [item]” is displayed using the Link - Action (primary) component.
• The “Add a new [item]” link directs the user to a new page with the form elements for adding an item.
• Upon completion, a “add” or “update” button returns the user to the original page with the new item added. A “Cancel” button returns the user to the original page without any changes.

Code considerations

How to use “Add item” link in Array Data details how to implement this variation.

When to use the add item variation

• Most of the information being requested is already available. If most of the information being requested is already on file then this variation works well because it presents to the user what we have on file and allows them to add items that are missing.
• Information on file is not contact information coming from VA.gov Profile. If the information on file is not coming from VA.gov Profile then this variation presents the data clearly and is preferred. If the information on file IS coming from VA.gov Profile then the “Contact information” variation is preferred.

About single page usage

While the single-page variation is currently used on VA.gov, it is no longer the preferred variation for this pattern. The multi-page pattern is recommended for new designs.