How I Built A Custom Stepper/Wizard Component Using The Angular Material CDK

Update 12.02.2018: Meanwhile, I have created a PR to the Angular Material repository and added there an official guide

I recently had to refactor a quite complex legacy Angular component and want to share my experiences with you.

The Legacy Component

The component should look this way per design:

You can freely navigate through the content by clicking either the navigation arrows or clicking on a certain step in the navigation area at the bottom.

The HTML template of the legacy component looked similar to this simple example:

1<div *ngIf="isContent1 && !isContent2 && !isFinished && !noError">Content 1</div>
2
3<div *ngIf="!isContent1 && isContent2 && !isFinished && !noError">Content 2</div>

So basically, there was a div container for each content page with multiple *ngIf statements. As only one content container could be visible per time, the *ngIf directives controlled their visibility.

Maybe at first glance, this sounds not that bad for you, but this approach had some significant problems:

• It contained large and confusing ngIf statements.
• Accessibility was not considered.
• Keyboard interactions were not supported by default.
• Managing which state is active had to be implemented manually.
• It is a custom solution that needs to be tested.
• It provided a non-scalable component architecture.

Additionally, we got a new requirement: It should be possible to switch between the content pages linearly. That means going from the first content page to the second content page should only be possible if the first page is completed, and going backward should not be allowed.

Refactoring

To fulfill the new requirement, I started research for existing components that provide a similar logic and found, for example, Angular Archwizard.

This excellent component also worked fine with the latest Angular version, but I could not easily modify the styling for our design requirements.

So I continued my research and stumbled upon the Angular Material CDK Stepper, which was exactly what I was looking for.

Angular Material CDK

On the official website, they describe the Component Dev Kit (CDK) as:

The Component Dev Kit (CDK) is a set of tools that implement common interaction patterns whilst being unopinionated about their presentation. It represents an abstraction of the core functionalities found in the Angular Material library, without any styling specific to Material Design. Think of the CDK as a blank state of well-tested functionality upon which you can develop your own bespoke components.

The CDK is divided into two parts: "Common Behaviors" and "Components".

Common Behaviors

Tools for implementing common application features

This is a list of common behaviors provided by the CDK:

Components

Unstyled components with useful functionality

The following image shows the list of components provided by the CDK:

CDK Stepper

The CdkStepper was exactly what I was looking for: A well-tested stepper functionality that I can design however I want to. It consists of a CdkStep used to manage the state of each step in the stepper and the CdkStepper, which contains the steps (CdkStep) and primarily handles which step is active.

Getting Started

It is straightforward to add the CDK to your Angular project:

npm install --save @angular/cdk

Or alternatively for Yarn:

yarn add @angular/cdk

You also need to add the CdkStepperModule to your Angular module:

1import { NgModule } from '@angular/core'
2import { BrowserModule } from '@angular/platform-browser'
3import { CdkStepperModule } from '@angular/cdk/stepper' // this is the relevant important
4
5import { AppComponent } from './app.component'
6
7@NgModule({
8  imports: [BrowserModule, CdkStepperModule], // add the module to your imports
9  declarations: [AppComponent],
10  bootstrap: [AppComponent],
11})
12export class AppModule {}

Demo Stepper Project

As the official documentation does not provide any code examples, I created a simple demo project on Stackblitz which I want to describe in the following sections.

Create CustomStepperComponent

The first step was to create a new Angular component for the CdkStepper to be able to modify it. Therefore, the component needs to extend from CdkStepper. The following example is a minimal implementation of a custom CDK stepper component:

1import { Directionality } from '@angular/cdk/bidi'
2import { ChangeDetectorRef, Component } from '@angular/core'
3import { CdkStepper } from '@angular/cdk/stepper'
4
5@Component({
6  selector: 'app-custom-stepper',
7  templateUrl: './custom-stepper.component.html',
8  styleUrls: ['./custom-stepper.component.css'],
9  providers: [{ provide: CdkStepper, useExisting: CustomStepperComponent }],
10})
11export class CustomStepperComponent extends CdkStepper {
12  constructor(dir: Directionality, changeDetectorRef: ChangeDetectorRef) {
13    super(dir, changeDetectorRef)
14  }
15
16  onClick(index: number): void {
17    this.selectedIndex = index
18  }
19}

The HTML template for this basic component:

1<ng-container [ngTemplateOutlet]="selected.content"></ng-container>
2
3<!-- This is the navigation bar of the stepper -->
4<footer>
5  <button cdkStepperPrevious>Previous</button>
6  <button *ngFor="let step of _steps; let i = index;" (click)="onClick(i)">Step {{i + 1}}</button>
7  <button cdkStepperNext>Next</button>
8</footer>

We can now use our new CustomStepperComponent in another component:

1<app-custom-stepper>
2  <cdk-step>
3    <input type="text" name="a" value="a" />
4  </cdk-step>
5  <cdk-step>
6    <input type="text" name="b" value="b" />
7  </cdk-step>
8</app-custom-stepper>

You must wrap each step inside a <cdk-step> tag. For multiple steps, you can of course, use *ngFor and use your custom step component inside:

1<app-custom-stepper>
2  <cdk-step *ngFor="let step of mySteps; let stepIndex = index">
3    <my-step-component [step]="step"></my-step-component>
4  </cdk-step>
5</app-custom-stepper>

Linear Mode

The above example allowed the user to navigate between all steps freely. The CdkStepper additionally provides the linear mode, which requires the user to complete previous steps before proceeding.

You can either use a single form for the entire stepper or a form for each step to validate if a step is completed. Alternatively, you can pass the completed property to each step and set the property value depending on your logic without using a form.

A simple example without using forms could look this way:

1<app-custom-stepper linear>
2  <cdk-step editable="false" [completed]="completed">
3    <input type="text" name="a" value="Cannot proceed to next step" />
4    <button (click)="completeStep()">Complete step</button>
5  </cdk-step>
6  <cdk-step editable="false">
7    <input type="text" name="b" value="b" />
8  </cdk-step>
9</app-custom-stepper>

1export class MyComponent {
2  completed = false
3
4  completeStep(): void {
5    this.completed = true
6  }
7}

The steps are marked as editable="false" which means that the user cannot return to this step once it has been marked as completed. It is impossible to navigate to the second step until the first one has been completed by clicking the Complete Step button.

If you are then on step 2 it is impossible to navigate back to step 1.

Conclusion

I am pleased with the CdkStepper, and it provided all the functionality I needed to refactor my legacy component. It was not necessary to write tests for this logic, and it automatically includes keyboard interaction support and cares about accessibility.

My advice is: If you ever need to implement a common behavior or component logic for your Angular application, please first look at the Angular Material CDK or similar libraries. Do not implement them yourself, as you will never get the same level of quality as from a maintained, widely-used open-source project like Angular Material.