Agriculture Design System
Beta
Design System for the Export Service

Progress indicator

Progress indicators show users the number of steps in a task, where they are up to in the process and how much is left to do.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/progress-indicator';
Open in Playroom, opens in a new tab
<ProgressIndicator
	items={[
		{ label: 'Introduction', status: 'done', href: '#' },
		{ label: 'Submit evidence', status: 'saved', href: '#' },
		{ label: 'Organisations', status: 'started', href: '#' },
		{ label: 'Business contacts', status: 'error', href: '#' },
		{ label: 'Case studies', status: 'todo', href: '#' },
		{ label: 'Attachments', status: 'started', href: '#', isActive: true },
		{ label: 'Review and submit', status: 'blocked', href: '#' },
	]}
/>

Progress indicators are used to show users how many steps are needed to complete a form and where they are in the process of completing it. This helps users know how much is left to do and how far along they are.

Progress indicators can be applied to larger tasks that can be completed in any order and returned to at a later date, like doing a tax return or applying for a driver’s licence.

Progress indicators can be applied to multi-step forms if the form has a known number of steps to be completed. 1

Avoid adding or removing pages to a multi-step form where a progress indicator is used as this can confuse and mislead users. Consider another approach if the number of steps might change due to user input. 2

Do

  • display steps in order from top to bottom
  • allow users to navigate to any step
  • use in forms and multi-page processes
  • use for processes of 2 - 10 steps
  • always present the mobile menu closed by default
  • pair with Task list if nesting is required
  • ensure step names match H1s and truncate if long
  • frontload keywords
  • group related steps.

Don’t

  • dynamically or conditionally change the number of steps in a progress indicator list
  • use for fewer than 2 steps
  • disable steps - allow users to navigate to pages and use Page alerts to indicate a step is not available yet
  • have any other components in the left-hand column
  • add the step number to the text - list only the action the user needs to take
  • mix with other navigation patterns - for example, Side nav
  • change labels or icons
  • make progress indicators a sticky nav item as this may cause reading order issues.

Background

The background of the Progress indicator must match the background it is being placed on.

If the Progress indicator is placed on a bodyAlt background, please set the background prop to bodyAlt.

Status

The status prop can be used to indicate the status of each item. The following values are available:

Available statuses for a Progress Indicator
StatusLabelDescription
todoNot startedThis step is available for the user to start.
startedIn progress

This step has been started and still needs to be completed.

doneCompleted

This step is complete. The user has submitted valid data and it has been verified (where necessary).

blockedCannot start yet

This step is not yet available for the user to start.

savedSaved

This step has valid saved data that can still be changed.

errorErrorThis step has an error that requires attention.

Active state handling

The isActive: true property needs to be applied to the currently active item.

Currently, only the 'started', and 'blocked' statuses may receive the isActive: true property.

If the user navigates to a page that is a different status, the status of that page should be changed to 'started' (unless 'blocked' is more appropriate).

Buttons

If an item does not specify an href attribute, a button element will be rendered. This enables you to respond to various mouse events, such as onClick.

<ProgressIndicator
	items={[
		{ label: 'Introduction', status: 'done', onClick: console.log },
		{ label: 'Submit evidence', status: 'saved', onClick: console.log },
		{ label: 'Organisations', status: 'started', onClick: console.log },
		{ label: 'Business contacts', status: 'error', onClick: console.log },
		{ label: 'Case studies', status: 'todo', onClick: console.log },
		{
			label: 'Attachments',
			status: 'started',
			onClick: console.log,
			isActive: true,
		},
		{ label: 'Review and submit', status: 'blocked', onClick: console.log },
	]}
/>

Hiding the sub title

The Progress indicator component displays a subtitle "x of y steps completed" by default. To hide this subtitle, set the hideSubtitle prop to true.

<ProgressIndicator
	hideSubtitle
	items={[
		{ href: '#', label: 'Introduction', status: 'done' },
		{ href: '#', label: 'Organisations', status: 'started' },
		{
			href: '#',
			label: 'Business contacts',
			status: 'started',
			isActive: true,
		},
		{ href: '#', label: 'Case studies', status: 'todo' },
		{ href: '#', label: 'Attachments', status: 'blocked' },
	]}
/>

Notes

  1. W3C Multi-page Forms

  2. U.S. Web Design System (USWDS) Step indicator

  • Task list Task list is a navigation tool that show users what input is required to complete a task or transaction.