Progress Indicator - Navigation

Also known as: Form navigation, Progress navigation, Step navigation

Examples

Default

The person is viewing step 2, which is the furthest step they’ve reached. Step 1 is completed, and steps 3 and 4 are locked.

View va-progress-indicator-navigation default in Storybook

Returning to a completed step

The person went back to step 1 to review their answers. Step 1 has the highlight for the step they’re viewing, and step 2 stays in progress.

View va-progress-indicator-navigation returning to a completed step in Storybook

All steps reached

The person is viewing the last step. Every earlier step is completed, and no steps are locked.

View va-progress-indicator-navigation all steps reached in Storybook

First step in progress on mobile

Below 640px wide, the list collapses behind a Select a form step button. This example shows the first step in progress, with every later step locked. To expand the list, select the Select a form step button.

View va-progress-indicator-navigation first step in progress in Storybook

Usage

When to use Progress Indicator - Navigation

• Tracking progress in multi-step forms. Use this component in forms with several steps where people need to know where they are, what they’ve finished, and what’s left.
• Returning to earlier answers. Use it when people may need to go back to a step they’ve already reached to review or change their answers. They can get there with a single selection instead of selecting Back over and over.
• Preparing for what’s ahead. Use it when seeing every step up front helps people gather what they need before they start. A review step at the end of the list also shows people they can check their answers before they submit.
• Replacing Progress Bar - Segmented. Use it in place of Progress Bar - Segmented when people need to move between steps, not just see their progress.

When to consider something else

• Showing progress only. Use Progress Bar - Segmented when people only need to see their progress. They move through the form with the Back and Continue buttons.
• Navigating outside of a form. Use Side Navigation to help people move between a group of related pages.
• Navigating within a single page. Use On This Page to help people jump to sections of the page they’re on.
• Explaining a process that happens over time. Use Process List to explain steps that span multiple interactions or a long period of time, such as what happens after someone submits a claim.

How this component works

Progress Indicator - Navigation combines the progress tracking of Progress Bar - Segmented with the navigation of Side Navigation. It shows each step of a form as a row in a vertical, subway-style list. Each row has a dot on a connecting line, with the step label to the right.

By default, each step label starts with a step number, such as Step 1: Personal information. The component figures out each step’s state from 2 values: the step the person is viewing and the furthest step they’ve reached. Each step is in one of 3 states.

• Completed. Every step before the furthest step reached. These steps show a filled dot, a link, and a Completed status label.
• In progress. The furthest step reached. This step shows a link and an In progress status label.
• Locked. Every step after the furthest step reached. These steps show a hollow dot and plain text instead of a link, so people can’t skip ahead.

This page calls completed and in-progress steps “reached” steps.

The step the person is viewing also gets a highlighted background and a bold label. This is usually the in-progress step. If the person goes back to review an earlier step, the highlight moves to that completed step. The in-progress step keeps its status.

Each step link goes to the first page of that step.

This component doesn’t replace the form’s Back and Continue buttons. People still use those buttons to move forward, since steps past their progress are locked. The U.S. Web Design System (USWDS) designed its step indicator to work alongside Back and Next buttons, not to act as navigation on its own. This component intentionally extends that idea by letting people return to steps they’ve already reached.

Behavior

Web

• Trigger. On desktop, people select a completed or in-progress step in the list. On mobile, they first select the Select a form step button to expand the list.
• Rules. Only completed and in-progress steps are links. Locked steps aren’t interactive. Selecting a step link takes people to the first page of that step.
• Feedback. The step people are viewing has a highlighted background and a bold label. Reached steps change background color on hover and show a focus outline inside the row. Each reached step shows a visible status label.
• Loops and modes. As people continue through the form, the next step changes from locked to in progress. The previous step changes to completed. Answers can also change the list. For example, an answer might add or remove a step, or reset progress. The component updates the list, but it doesn’t announce these changes.

Placement

The component doesn’t position itself on the page. Your page layout controls where it appears and whether it stays in view as people scroll.

Desktop view

At the tablet breakpoint (640px) and wider, place the component at the top of the left column in a two-column layout, below the breadcrumb. The Form steps heading and the full list are always visible.

Mobile view

Below 640px, the list collapses behind a Select a form step button. Place the component below the breadcrumb and above the form content. The list is collapsed by default. When people expand it, the list pushes the page content down instead of covering it.

Code considerations

Keep these details in mind when you build with this component.

• Application-owned logic. The component only displays progress and reports selections. It doesn’t read form configuration, form data, or application state. Your application decides which step is current and how far someone has reached. It also owns saving progress, resetting progress, announcing changes, and moving focus after navigation.
• Cross-chapter dependencies. In complex forms, changing an earlier answer can add, remove, or reorder later steps. Here are some potential solutions for various scenarios that may occur while your users traverse multiple pages at a time.
  • Reset affected steps. If an earlier answer can change later steps, move progress back to the changed step and lock later steps until people move through the updated flow.
  • Restore when valid. If someone returns to a previous path and their later answers still apply, restore the step state they had before.
  • Confirm destructive changes. Use the Modal component before clearing entered data or resetting completed steps.
  • Keep updates in sync. Derive the step list, step states, and review page from the same source of truth.
  • Example from VA Form 526. Adding a new condition can temporarily reset progress because it adds a mental health step. If the person cancels, restore the previous path and reached steps.
• Step data. Pass steps to progress-indicator-nav-items as an array of objects. Each object needs a key, title, and href. Set this as a JavaScript property, not an HTML attribute, since an attribute can’t hold an array.
• Progress state. Set current-step to the index of the step being viewed. Set max-step-index to the index of the furthest step reached. Both are required, and both start at 0. You can’t set the state of an individual step.
• Default link behavior. Selecting a reached step follows its href. It also emits a vaStepClick event with the step’s index and key.
• Router integration. In single-page applications, set router-link to stop the browser from following href. Then handle routing in your vaStepClick handler.
• New tabs and windows. Ctrl-click, Command-click, Shift-click, and Option-click (Alt-click) always go to the browser, even with router-link set. This lets people open a step in a new tab or window. These clicks don’t emit vaStepClick.
• Locked steps. Locked steps don’t emit vaStepClick.
• Analytics. The component doesn’t send analytics events yet. To track step selections, use your vaStepClick handler. Clicks that open a new tab or window aren’t reported.

Code usage

Content considerations

• Keep step titles short. Aim for 35 characters or fewer, or about 3 to 5 words. Don’t go over 45 characters. Longer titles wrap and create uneven rows that make the list harder to scan.
• Match your form’s step titles. Use the same step titles people see elsewhere in the form, so they recognize where each link goes.
• Don’t number your titles. The component adds a prefix and number to each title, such as Step 1: Personal information. Don’t include numbers or the word Step in your titles.
• Include the review step. List the final review step (e.g., Review your application) so people know they can check their answers before they submit.
• Change default labels only when needed. The heading, the mobile button, and the title prefix have default text. You can change them with the header, mobile-header, and title-prefix properties. Keep the wording consistent with how your form refers to its steps.
• Account for built-in status text. The Completed and In progress status labels are built in, and you can’t change them. Locked steps also include built-in screen-reader-only text that tells people to complete the earlier steps first.

Accessibility considerations

• Focus order and markup placement. Place the component after the breadcrumb and before the main content in the focus order. When possible, place it outside the <main> element.
• Landmark name. The component renders a <nav> landmark. Its visible heading (Form steps by default) gives the landmark its accessible name. If you set header to an empty string, the landmark uses nav-aria-label as its name instead. If nav-aria-label isn’t set, the name falls back to Form steps.
• Heading level. The component shows a single heading at each screen size. On desktop, it’s the Form steps heading. On mobile, a heading wraps the Select a form step button. Both are h2 by default. Use header-level to set the level for both so they fit your page’s heading structure.
• Link semantics. Reached steps are native links. Screen readers announce them as links and include them in the links list. People activate them with the Enter key.
• Current step. The step being viewed has aria-current="step", so screen readers announce it as the current step.
• Status without color alone. Each reached step has a visible status label, and screen readers announce it after the step label. Locked steps are plain text, not links, with screen-reader-only text that explains why.
• Mobile disclosure. On mobile, the Select a form step button uses aria-expanded to report whether the list is open. When the list is collapsed, the component hides the navigation landmark entirely. This keeps screen reader users from landing on an empty navigation region.
• List change announcements. The component doesn’t include a live region. When an answer adds or removes a step, or resets or restores progress, your application needs to tell people what changed. For example, show an Alert on the page and move focus to it. Make these announcements outside the component’s shadow Document Object Model (DOM). Safari with VoiceOver doesn’t reliably announce live regions inside shadow DOM.
• Focus after navigation. The component doesn’t control the page. When someone selects a step and the new page loads, move focus as described in Managing focus in form flows.

Related

• Progress Bar - Segmented
• Side Navigation
• Process List
• On This Page
• Form templates

Component checklist

Provide feedback

Share your feedback, report issues, or suggest improvements for the Progress Indicator - Navigation component. Your input helps us make the design system better for everyone.

• Get immediate support in #platform-design-system for technical or urgent issues.
• Explore all feedback channels for additional ways to share your input.