Stepper Nav

Usage

When to use

• In complex flows that are broken up into multiple steps.
• To communicate what has and has not been completed in a multi-step flow.
• For a single page multi-step flow that requires completion.

When not to use

• For simple flows, use the form pattern on a single page.
• For simple forms or when progress doesn't need to be tracked, use structured page content.
• For a progression of tasks that doesn’t require a user to remain on the same page, use the Stepper List.

Interactive vs non-interactive

The Stepper Nav supports both interactive (default) and non-interactive variants.

Interactive steps

Users can navigate backwards within the Stepper Nav steps but cannot navigate forwards unless they have completed the current step. This creates consistency for step flow behavior and the order of operations.

Non-interactive steps

The non-interactive variant is for read-only purposes and does not allow backwards navigation.

Content

The Stepper Nav supports a title and an optional description. Content should be limited to only what is necessary, and long form content should live within the body of the Step.

Title

Titles provide an overview to help users understand what tasks need to be completed. Titles are required and should be brief.

Description

Descriptions provide additional context about the step and are optional. We recommend that all steps either have a description or do not.

Number of steps

We recommend a maximum of 4 steps. If that isn’t possible, be mindful of how the content within the title and description will wrap on smaller screens.

Spacing

There should be 32px of spacing above the Stepper Nav and 24px below.

Resizing behavior

Each step scales evenly to fit within the total width of the Stepper Nav. This ensures consistent touch target sizes for hover, active, and focus states. The total width of the Stepper Nav should match the page content width.

Responsive layout

At browser widths of 550px and below, the steps will stack vertically and not display a connecting progress bar.

Composition with other components

Always pair the Stepper Nav with appropriate navigation Buttons such as "Next" and "Previous". Buttons can be wrapped with a Button Set to ensure consistent spacing between them.

If backwards navigation is allowed, use an interactive Stepper Nav, otherwise use the non-interactive variant.

How to use this component

The Stepper Nav component is used to track the linear progress of a user in a given on-page flow.

To use this component, you can either pass in the contextual Step and Panel components, or use the @steps argument to pass in an array of steps.

Using contextual components

The Hds::Stepper::Nav::Step and Hds::Stepper::Nav::Panel are yielded as contextual components.

<Hds::Stepper::Nav @ariaLabel="Basic usage" as |S|>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>

  <S.Panel>Content 1</S.Panel>
  <S.Panel>Content 2</S.Panel>
  <S.Panel>Content 3</S.Panel>
</Hds::Stepper::Nav>

Using the @steps argument

When using the @steps argument, use the named block <:body> to pass in step content. This can be used if the template for steps content is consistent across steps, or conditionally rendered based on arguments other than the currentStep.

<Hds::Stepper::Nav
  @currentStep={{this.demoCurrentStep}}
  @steps={{array
    (hash title="Step 1")
    (hash title="Step 2")
    (hash title="Step 3")
  }}
  @ariaLabel="Using steps argument"
  @onStepChange={{this.demoOnStepChange}}
>
  <:body>
    {{#if (eq this.demoCurrentStep 0)}}
      Content 1
    {{else if (eq this.demoCurrentStep 1)}}
      Content 2
    {{else}}
      Content 3
    {{/if}}
    {{#if true}}
      Conditional content
    {{/if}}
  </:body>
</Hds::Stepper::Nav>

Step status

The status of steps is controlled automatically through the @currentStep argument. The argument is zero-indexed and sets the active step to the value provided. The status of a step is determined in the following ways in relation to the @currentStep.

• A step equal to @currentStep is active
• All steps less than @currentStep are completed
• All steps greater than @currentStep are incomplete

By default, @currentStep is equal to 0.

<Hds::Stepper::Nav
  @currentStep={{this.demoCurrentStep}}
  @ariaLabel="Status"
  @onStepChange={{this.demoOnStepChange}}
  as |S|
>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>

  <S.Panel>Content 1</S.Panel>
  <S.Panel>Content 2</S.Panel>
  <S.Panel>Content 3</S.Panel>
</Hds::Stepper::Nav>

Interactivity

The @isInteractive argument controls if navigation between steps is allowed using the steps. By default @isInteractive is true.

Interactive

When @isInteractive is set to true, users can navigate to completed steps by clicking on the step. Users can only navigate to completed steps, not incomplete ones.

When a click on a step occurs, the @onStepChange handler can be used to pass a custom function to update the current step number.

<Hds::Stepper::Nav
  @currentStep={{this.demoCurrentStep}}
  @ariaLabel="Interactive"
  @onStepChange={{this.demoOnStepChange}}
  as |S|
>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>

  <S.Panel>Content 1</S.Panel>
  <S.Panel>Content 2</S.Panel>
  <S.Panel>Content 3</S.Panel>
</Hds::Stepper::Nav>

Not interactive

When @isInteractive is set to false, the component steps do not allow navigation between steps.

<Hds::Stepper::Nav
  @currentStep={{1}}
  @isInteractive={{false}}
  @ariaLabel="Interactive"
  as |S|
>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>

  <S.Panel>Content 1</S.Panel>
  <S.Panel>Content 2</S.Panel>
  <S.Panel>Content 3</S.Panel>
</Hds::Stepper::Nav>

Without panels

The component can be used without the [S].Panel contextual component, or <:body> named block. In this use case, the component operates similar to a static list. This can be used if the content of the steps is outside of the component.

<Hds::Stepper::Nav
  @isInteractive={{false}}
  @ariaLabel="Standalone contextual components"
  as |S|
>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>
</Hds::Stepper::Nav>
Steps content

Composition with other components

The Stepper Nav should be paired with appropriate navigation Buttons. Buttons can be wrapped with a Button Set to ensure consistent spacing between them.

<Hds::Stepper::Nav
  @currentStep={{this.demoButtonsCurrentStep}}
  @ariaLabel="Component composition"
  @onStepChange={{this.demoButtonsOnStepChange}}
  as |S|
>
  <S.Step>
    <:title>Step 1</:title>
  </S.Step>
  <S.Step>
    <:title>Step 2</:title>
  </S.Step>
  <S.Step>
    <:title>Step 3</:title>
  </S.Step>
  <S.Panel>
    Content 1
    <Hds::Button @text="Next" {{on "click" this.onNextClickDemo}} />
  </S.Panel>
  <S.Panel>
    Content 2
    <Hds::ButtonSet>
      <Hds::Button
        @text="Previous"
        @color="secondary"
        {{on "click" this.onPreviousClickDemo}}
      />
      <Hds::Button @text="Next" {{on "click" this.onNextClickDemo}} />
    </Hds::ButtonSet>
  </S.Panel>
  <S.Panel>
    Content 3
    <Hds::Button
      @text="Previous"
      @color="secondary"
      {{on "click" this.onPreviousClickDemo}}
    />
  </S.Panel>
</Hds::Stepper::Nav>

Component API

Stepper::Nav

Contextual components

[S].Step

The Stepper::Nav::Step component, yielded as contextual component.

[S].Panel

The Stepper::Nav::Panel component, yielded as contextual component.

Anatomy

States

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Keyboard navigation

Focus on the active step.

Move between completed and active steps.

If focus is on the first step, left arrow moves focus to the last completed or active step. If focus is on the last completed or active step, right arrow moves focus to the first completed or active step.

Activate step to display step content.

Move to interactive element within the content area.

Applicable WCAG Success Criteria

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.18.1

Added new Stepper Nav component