StepTracker

import { StepTracker } from '@uhg-abyss/web/ui/StepTracker';

currentStep

hideStepNumbers

hideStepStatus

<StepTracker
  steps={[
    'Personal Information',
    'Qualifications',
    'Practice Information',
    'Locations',
    'Review & Confirm',
  ]}
  currentStep={1}
  hideStepNumbers={false}
  hideStepStatus={false}
/>

Usage

StepTracker works best in conjunction with the usePagination hook. usePagination handles the state management and provides methods to programmatically update the state externally.

There are two ways to provide the labels for the steps, the steps prop and child elements. Note that these approaches are mutually exclusive.

Using the steps prop

The simplest method of providing step labels is to use the steps prop. This accepts an array of strings and will display the labels in the order provided.

() => {
  const paginationProps = usePagination({ pages: 6 });

  const steps = [
    'Personal Information',
    'Qualifications',
    'Practice Information',
    'Locations',
    'Review & Confirm',
  ];

  return (
    <React.Fragment>
      <StepTracker
        steps={steps}
        currentStep={paginationProps.state.currentPage}
      />
      <Layout.Group style={{ marginTop: 10 }}>
        <Button
          onClick={paginationProps.previousPage}
          variant="outline"
          isDisabled={!paginationProps.canPreviousPage}
        >
          Previous
        </Button>
        <Button
          onClick={paginationProps.nextPage}
          isDisabled={!paginationProps.canNextPage}
        >
          Next
        </Button>
      </Layout.Group>
    </React.Fragment>
  );
};

Editable Example

Using child elements

If more customization for individual steps is required, such as when styling or adding a data-testid, use the StepTracker.Step component as the children of the StepTracker instead.

() => {
  const paginationProps = usePagination({ pages: 6 });

  return (
    <React.Fragment>
      <StepTracker currentStep={paginationProps.state.currentPage}>
        <StepTracker.Step label="Personal Information" data-testid="step-1" />
        <StepTracker.Step label="Qualifications" />
        <StepTracker.Step label="Practice Information" />
        <StepTracker.Step label="Locations" />
        <StepTracker.Step label="Review & Confirm" />
      </StepTracker>
      <Layout.Group style={{ marginTop: 10 }}>
        <Button
          onClick={paginationProps.previousPage}
          variant="outline"
          isDisabled={!paginationProps.canPreviousPage}
        >
          Previous
        </Button>
        <Button
          onClick={paginationProps.nextPage}
          isDisabled={!paginationProps.canNextPage}
        >
          Next
        </Button>
      </Layout.Group>
    </React.Fragment>
  );
};

Editable Example

Pagination

Set the pages variable to match how many pages you would like to display and start to set the starting page.

If pages is set to the number of steps plus one, as shown below, then each step can be marked "Completed". This state would typically be used on a page to indicate that the user has completed the process.

If pages is set equal to the number of steps, as shown below, the final page will never be marked "Completed".

Final text in button

Use code similar to the example below to change the button on the final page from "Next" to "Submit".

Hide step numbers

Use the hideStepNumbers prop to remove the numbers next to each step's label. Note that for accessibility reasons, the numbers will still be read by screen readers. Additionally, even if hideStepNumbers is set to true, the numbers will still be displayed on the mobile width.

Hide step status

Use the hideStepStatus prop to remove the step status text. Note that for accessibility reasons, the status will still be read by screen readers.

Mobile width

On screens less than 744px wide, the StepTracker will only show the current step's title. Resize the window to see the change!

Comparison to Timeline

Timeline and StepTracker are similar components, but should not be used interchangeably. Both components display a history of completed steps in, the current progress of, and information about the remaining steps in a process. What differentiates one from the other is whether the information displayed is based on immediate user engagement with the user interface or not.

Timeline

The Timeline component is used to inform users of the status of a process with no immediate user input. An example is a claims submission status page where the user can see the progress of their claim through the various stages, but cannot interact with the steps directly.

The StepTracker is used to guide people through a number of steps to complete in a process. The user navigates through the steps with other components in the UI, typically buttons. An example is a multi-step form where the user fills out information in each step and can navigate back and forth between steps.

StepTracker Props

Name	Type	Default	Required	Description
children	never \| React.ReactElement<Abyss.ForwardRefComponent, string \| React.JSXElementConstructor<...>>[]	-	-	The steps to display in the StepTracker; mutually exclusive with steps
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties \| Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
currentStep	number	-		The current step number
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
hideStepNumbers	boolean	false	-	If true, the step numbers will be hidden
hideStepStatus	boolean	false	-	If true, the step status will be hidden
steps	string[] \| never	-		The steps to display in the StepTracker; mutually exclusive with children

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

StepTracker.types.ts

StepTracker.Step Props

Name	Type	Default	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties \| Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
label	string \| React.JSX.Element	-		The step label

Below are the link(s) to the relevant GitHub type files:

StepTrackerStep.types.ts

StepTracker Classes

Class Name	Description
.abyss-step-tracker-root	StepTracker root container
.abyss-step-tracker-steps-container	StepTracker steps container
.abyss-step-tracker-mobile-step-label-container	StepTracker mobile step label container
.abyss-step-tracker-mobile-step-label	StepTracker mobile step label text

StepTracker.Step Classes

Class Name	Description
.abyss-step-tracker-step-root	StepTracker step root container
.abyss-step-tracker-step-${number}-root	StepTracker step root container for the given stepNumber
.abyss-step-tracker-step-label-container	StepTracker step label container
.abyss-step-tracker-step-label	StepTracker step label text
.abyss-step-tracker-step-status	StepTracker step status text
.abyss-step-tracker-progress-line-container	StepTracker step progress line container
.abyss-step-tracker-step-indicator	StepTracker step indicator container
.abyss-step-tracker-step-indicator-icon	StepTracker step indicator icon

The StepTracker is used to display a user's progress through a multistep process, such as an input form. It is intended to be an enhancement to, not a replacement for, regular back/next navigation.

The following examples can be used to verify screen reader support for the StepTracker using a version with all text visible and a version with optional text hidden.

Full Text

Minimal Text

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

StepTracker Tokens

Token Name	Value
step-tracker.color.text.status.complete	#007000
step-tracker.color.text.status.incomplete	#4B4D4F
step-tracker.color.text.status.current	#4B4D4F
step-tracker.color.text.label	#4B4D4F
step-tracker.color.icon.complete	#007000
step-tracker.color.border.track.complete	#007000
step-tracker.color.border.track.incomplete	#4B4D4F
step-tracker.color.border.indicator.complete	#007000
step-tracker.color.border.indicator.incomplete	#4B4D4F
step-tracker.color.surface.indicator	#FFFFFF
step-tracker.sizing.all.icon	20px
step-tracker.spacing.gap.vertical.container.mobile	4px
step-tracker.spacing.gap.vertical.container.step	8px
step-tracker.spacing.gap.vertical.container.content	4px
step-tracker.spacing.padding.horizontal.container.label	8px
step-tracker.spacing.padding.horizontal.container.status	8px

Migration Information

Usage​

Using the steps prop​

Using child elements​

Pagination​

Final text in button​

Hide step numbers​

Hide step status​

Mobile width​

Comparison to Timeline​

Timeline​

StepTracker​