Web Components Stepper Overview

The Web Components Stepper Component provides a wizard-like workflow and is used for showing progress through numbered steps. It enables developers to divide a lengthy content into a sequence of logical steps, helping end-users more easily navigate the entire process. The Web Components Stepper is displayed as a vertical or a horizontal line. The Web Components Stepper has multiple features like step validation, styling, orientation and keyboard navigation.

Web Components Stepper Example

The following Ignite UI for Web Components Stepper Example below shows the component in action. It visualizes the process that an end-user must pass through to configure an order details, following several consecutive steps.

Getting Started with Web Components Stepper

First, you need to install the Ignite UI for Web Components by running the following command:

npm install igniteui-webcomponents

Before using the Stepper, you need to register it as follows:

import { defineComponents, IgcStepperComponent } from 'igniteui-webcomponents';

defineComponents(IgcStepperComponent);

For a complete introduction to the Ignite UI for Web Components, read the Getting Started topic.

Now you can start with a basic configuration of the Web Components Stepper and its steps.

How To Use Web Components Stepper

The Step is the representation of every step that belongs to the Stepper. Steps provide Step.Invalid, Step.Active, Step.Optional, Step.Disabled and Step.Complete properties, which give you the ability to configure the step states according to your business requirement.

Declaring Web Components Stepper

Steps can be declared the following way:

<igc-stepper>
    <igc-step>
       <span slot="title">Step 1</span>
    </igc-step>
    <igc-step>
       <span slot="title">Step 2</span>
    </igc-step>
</igc-stepper>

For each step the user has the ability to configure the indicator, title and subtitle using the indicator, title, and subtitle slots.

For the title and subtitle slots, we recommend using <span> elements rather than heading elements (<h1>–<h6>). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component’s intended typography and layout. Using a <span> gives you a neutral container that inherits the component’s styles cleanly.

For the indicator slot, we also recommend using a <span> element for symbol or emoji indicators, and an <igc-icon> component for icon indicators.

<igc-stepper>
    <igc-step>
       <igc-icon slot="indicator" iconName="home"></igc-icon>
       <span slot="title">Home</span>
       <span slot="subtitle">Home Sub Title</span>
       <div>
          Step Content
       </div>
    </igc-step>
</igc-stepper>

Orientation in Web Components Stepper

You can customize the stepper orientation through the exposed Orientation property. It could be set to horizontal or vertical.

Horizontal Stepper Orientation

horizontal is the default value for the Stepper orientation property.

When the Web Components stepper is horizontally orientated you have the opportunity to determine whether the steps’ content would be displayed above or below the steps’ headers. This could be achieved by setting the Stepper ContentTop boolean property, which default value is false. In case it is enabled the steps’ content would be displayed above the steps’ headers.

Vertical Stepper Orientation

You can easily switch from the horizontal to vertical layout. In order to change the default orientation you should set the Orientation property to vertical.

The sample below demonstrates how stepper orientation and titles position could be changed runtime.

Step States

Web Components Stepper supports five steps states and each of them apply different styles by default:

• active - Determines whether the step is the currently displayed. By design, if the user does not explicitly set some step’s active attribute to true, the initial active step would be the first non-disabled step.
• disabled - Determines whether the step is intractable. By default, the disabled attribute of a step is set to false.
• invalid - Determines whether the step is valid. Based on its value it is decided whether the user will have the ability to move forward in linear stepper mode. Its default value is false.
• optional - By default, the optional attribute of a step is set to false. If validity of a step in linear stepper is not required, then the optional attribute can be enabled in order to be able to move forward independently from the step validity.
• complete - By default, the complete attribute of a step returns false. The user, however, can override this default complete behavior by setting the complete attribute as needed. When step is marked as complete not only that the style of the step header is changed by default, but also the style of the progress line between the completed step and the next one.

Linear Web Components Stepper

The Web Components Stepper gives you the opportunity to set its steps flow using the Linear property. By default, linear is set to false and the user is enabled to select any non-disabled step in the Stepper.

<igc-stepper linear="true">
    <igc-step>
        <span slot="title">Step 1</span>
    </igc-step>
    <igc-step>
        <span slot="title">Step 2</span>
    </igc-step>
</igc-stepper>

When the linear property is set to true, the stepper will require the current non-optional step to be valid before proceeding to the next one.

If the current non-optional step is not valid you cannot go forward to the next step until you validate the current one.

Step Interactions

Stepper provides the following API methods for step interactions:

• navigateTo – activates the step by given index.
• next - activates the next non-disabled step.
• prev – activates the previous non-disabled step.
• reset – resets the stepper to its initial state.

Customizing the Steps

The Ignite UI for Web Components Stepper gives you the ability to configure different options for titles, indicators and more.

This could be achieved through the StepType property of the Stepper. It takes the following values:

• Full (default value)
• Indicator
• Title

full

If titles and subtitles are defined, with this setup both indicators and titles would be rendered.

The user would also have the ability to define the position of the title for the steps, so it could be placed before, after, above or below the step indicator. The user can configure the title position using the TitlePosition property. It takes the following values:

• undefined (default value)
• end
• start
• bottom
• top

When the Web Components Stepper is horizontally orientated and the title position is not defined, the titles would be displayed below the indicators.

When the orientation is set to vertical and the title position is not defined, the titles would be displayed after the indicators.

indicator

If you want to display only indicators for the steps, set the stepType option to indicator.

The step indicator supports any content, however with the restriction that its size would be always 24 pixels. Having this in mind, we recommend using Icon or Avatar as step indicators.

Title

If you want to display only titles for the steps, set the stepType option to title.

In this way if subtitles are defined, they will also be rendered below the step title.

The sample below demonstrates all exposed step types and how they could be changed:

Dynamic Step Height

When the Stepper is horizontally oriented, the content area height is determined by the step with the most content. All other steps share this fixed height, which may result in visible empty space in steps with less content.

To override the fixed height and have the content area adapt to the active step’s content, set the —body-grid-rows CSS variable to 0fr (the default is 1fr):

igc-stepper {
  --body-grid-rows: 0fr;
}

Stepper Animations

The Web Components Stepper Animations provide the end-users with a beautiful experience interacting with the defined steps. The available animation options differ depending on the orientation of the stepper.

When the stepper is horizontally orientated, it is configured to use the slide animation by default. It also supports fade as an alternative. The animations are configured through the HorizontalAnimation input.

In a vertically orientated layout, the animation type could be defined using the VerticalAnimation property. By default, its value is set to grow and the user has the ability to set it to fade as well.

Setting none to both animation type inputs disables stepper animations.

The Stepper component also gives you the ability to configure the duration of the transition between the steps. This could be achieved through the AnimationDuration property, which takes a number as an argument and it is common to both orientations. The default value is set to 320ms.

Keyboard Navigation

The Ignite UI for Web Components Stepper provides a rich variety of keyboard interactions to the end-user. This functionality is enabled by default and allows end-users to easily navigate through the steps. The Web Components Stepper navigation is compliant with W3 accessability standards and convenient to use.

Key Combinations

• TAB - moves the focus to the next tabbable element
• SHIFT + TAB - moves the focus to the previous tabbable element
• ↓ - moves the focus to the header of the next accessible step when the stepper is vertically orientated
• ↑ - moves the focus to the header of the previous accessible step when the stepper is vertically orientated
• ← - moves the focus to the header of the previous accessible step in both orientations
• → - moves the focus to the header of the next accessible step in both orientations
• HOME - moves the focus to the header of the FIRST enabled step in the stepper
• END - moves the focus to the header of the LAST enabled step in the stepper
• ENTER or SPACE - activates the currently focused step

Styling Web Components Stepper

You can change the appearance of the Step, by using some of the exposed CSS parts listed below:

Using these CSS parts we can customize thе appearance of the Stepper component like this:

igc-step::part(title) {
  color: var(--ig-primary-500);
}
igc-step[active]::part(indicator) {
  background-color: var(--ig-primary-500);
}
igc-step::part(indicator) {
  background-color: var(--ig-surface-500);
}

API References

Additional Resources

• Ignite UI for Web Components Forums
• Ignite UI for Web Components GitHub