Stepper

Updated:

Provides a simple way to navigate a user through a multi-step process.

Detailed Description

The q2-stepper element is populated via q2-stepper-pane elements, each of which represents a single step in a multi-step process. At runtime, the q2-stepper element will automatically determine how many steps are available by counting the number of q2-stepper-pane elements in its body.

If the current-step attribute is set, the q2-stepper element will automatically display that step. If it is not provided, it will default to the first step.

A user may navigate to previous steps by clicking the bullet associated to it, however they will not be to navigate to future, uncompleted steps.

To unlock future steps, you may manually update the current-step attribute which will take the user to the specified step and update the last-enabled-step if necessary. You may also just update the last-enabled-step attribute, which will unlock the step without taking the user to it.

Steps With Status

The q2-stepper element is populated via q2-stepper-pane elements, each of which represents a single step in a multi-step process. At runtime, the q2-stepper element will build a navigation on the left side of the stepper which can be interacted with by the user.

Each instance of q2-stepper-pane can be in one of several states, that you are responsible for managing:

  • No status provided - The step is enabled.
  • status="complete" - The step is enabled but marked as completed.
  • status="error" - The step is enabled but marked as having errors.
  • status="locked" - The step is disabled.

Each of the statuses appears like this:

Step 1

This stepper has a total of 6 steps. This is step 1.

Step 2

This stepper has a total of 6 steps. This is step 2.

Step 3

This stepper has a total of 6 steps. This is step 3.

Step 4

This stepper has a total of 6 steps. This is step 4.

Step 5

This stepper has a total of 6 steps. This is step 5.

Step 6

This stepper has a total of 6 steps. This is step 6.

 
<q2-stepper current-step="3" last-enabled-step="5">
  <q2-stepper-pane id="step-1013" label="Step 1" description="This is number 1 of 6 steps.">
    <h3>Step 1</h3>
    <p>This stepper has a total of 6 steps. This is step 1.</p>
  </q2-stepper-pane>
  <q2-stepper-pane id="step-1002" label="Step 2" description="This is number 2 of 6 steps." status="error">
    <h3>Step 2</h3>
    <p>This stepper has a total of 6 steps. This is step 2.</p>
  </q2-stepper-pane>
  <q2-stepper-pane id="step-1009" label="Step 3" description="This is number 3 of 6 steps." status="complete" is-active>
    <h3>Step 3</h3>
    <p>This stepper has a total of 6 steps. This is step 3.</p>
  </q2-stepper-pane>
  <q2-stepper-pane id="step-1006" label="Step 4" description="This is number 4 of 6 steps." status="locked">
    <h3>Step 4</h3>
    <p>This stepper has a total of 6 steps. This is step 4.</p>
  </q2-stepper-pane>
  <q2-stepper-pane id="step-1005" label="Step 5" description="This is number 5 of 6 steps.">
    <h3>Step 5</h3>
    <p>This stepper has a total of 6 steps. This is step 5.</p>
  </q2-stepper-pane>
  <q2-stepper-pane id="step-1006" label="Step 6" description="This is number 6 of 6 steps.">
    <h3>Step 6</h3>
    <p>This stepper has a total of 6 steps. This is step 6.</p>
  </q2-stepper-pane>
</q2-stepper>

Properties

Learn more about properties.

currentStep
current-step

The currently selected step.

lastEnabledStep
last-enabled-step

The last step the user may navigate to.

Will be managed automatically if not provided.

Events

The q2-stepper element exposes events that can be used to send and receive data from the component based on user interaction.

Learn more about events.

change

Emitted when the selected step changes.

Event Detail Type signature

any

If an event handler is bound to the element using:

  • onchange property - The default handler will not fire, and the value must be updated in the custom handler.
  • addEventListener("change") method - The default handler will fire alongside the custom handler.

Methods

The q2-stepper element exposes methods that can be used to perform various actions on the component.

Learn more about methods.

selectStep

Test only

Emulates clicking a step in the stepper and emitting the change event.

You may provide either the step number or the stepper pane id.

If the value is invalid or the step is locked, the method will do nothing.

Type signature

selectStep(value: number | string) => Promise<void>

Release Notes

Initial Release

Accessibility Report

Tecton components are designed and tested to be WCAG compliant when used appropriately, and do not get released without proper validation. Developers should prefer not to set ARIA attributes when using components from the Tecton Design System.

The following CSS variables are available to override the default theme styles of the q2-steppercomponent.

Dependencies

Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!

  • q2-icon
  • q2-btn