Angular Material's stepper provides a wizard-like workflow by dividing content into logical steps.
Material stepper builds on the foundation of the CDK stepper that is responsible for the logic that drives a stepped workflow. Material stepper extends the CDK stepper and has Material Design styling.
There are two stepper components: mat-horizontal-stepper
and mat-vertical-stepper
. They can be used the same way. The only difference is the orientation of stepper.
mat-horizontal-stepper
selector can be used to create a horizontal stepper, and mat-vertical-stepper
can be used to create a vertical stepper. mat-step
components need to be placed inside either one of the two stepper components.
If a step's label is only text, then the label
attribute can be used.
<mat-vertical-stepper>
<mat-step label="Step 1">
Content 1
</mat-step>
<mat-step label="Step 1">
Content 2
</mat-step>
</mat-vertical-stepper>
For more complex labels, add a template with the matStepLabel
directive inside the mat-step
.
<mat-vertical-stepper>
<mat-step>
<ng-template matStepLabel>...</ng-template>
...
</mat-step>
</mat-vertical-stepper>
There are two button directives to support navigation between different steps: matStepperPrevious
and matStepperNext
.
<mat-horizontal-stepper>
<mat-step>
...
<div>
<button mat-button matStepperPrevious>Back</button>
<button mat-button matStepperNext>Next</button>
</div>
</mat-step>
</mat-horizontal-stepper>
The linear
attribute can be set on mat-horizontal-stepper
and mat-vertical-stepper
to create a linear stepper that requires the user to complete previous steps before proceeding to following steps. For each mat-step
, the stepControl
attribute can be set to the top level AbstractControl
that is used to check the validity of the step.
There are two possible approaches. One is using a single form for stepper, and the other is using a different form for each step.
Alternatively, if you don't want to use the Angular forms, you can pass in the completed
property to each of the steps which won't allow the user to continue until it becomes true
. Note that if both completed
and stepControl
are set, the stepControl
will take precedence.
When using a single form for the stepper, matStepperPrevious
and matStepperNext
have to be set to type="button"
in order to prevent submission of the form before all steps are completed.
<form [formGroup]="formGroup">
<mat-horizontal-stepper formArrayName="formArray" linear>
<mat-step formGroupName="0" [stepControl]="formArray.get([0])">
...
<div>
<button mat-button matStepperNext type="button">Next</button>
</div>
</mat-step>
<mat-step formGroupName="1" [stepControl]="formArray.get([1])">
...
<div>
<button mat-button matStepperPrevious type="button">Back</button>
<button mat-button matStepperNext type="button">Next</button>
</div>
</mat-step>
...
</mat-horizontal-stepper>
</form>
<mat-vertical-stepper linear>
<mat-step [stepControl]="formGroup1">
<form [formGroup]="formGroup1">
...
</form>
</mat-step>
<mat-step [stepControl]="formGroup2">
<form [formGroup]="formGroup2">
...
</form>
</mat-step>
</mat-vertical-stepper>
If completion of a step in linear stepper is not required, then the optional
attribute can be set on mat-step
.
By default, steps are editable, which means users can return to previously completed steps and edit their responses. editable="true"
can be set on mat-step
to change the default.
By default, the completed
attribute of a step returns true
if the step is valid (in case of linear stepper) and the user has interacted with the step. The user, however, can also override this default completed
behavior by setting the completed
attribute as needed.
By default, the step headers will use the create
and done
icons from the Material design icon set via <mat-icon>
elements. If you want to provide a different set of icons, you can do so by placing a matStepperIcon
for each of the icons that you want to override. The index
, active
, and optional
values of the individual steps are available through template variables:
<mat-vertical-stepper>
<ng-template matStepperIcon="edit">
<mat-icon>insert_drive_file</mat-icon>
</ng-template>
<ng-template matStepperIcon="done">
<mat-icon>done_all</mat-icon>
</ng-template>
<!-- Custom icon with a context variable. -->
<ng-template matStepperIcon="number" let-index="index">
{{index + 10}}
</ng-template>
<!-- Stepper steps go here -->
</mat-vertical-stepper>
Note that you aren't limited to using the mat-icon
component when providing custom icons.
Labels used by the stepper are provided through MatStepperIntl
. Localization of these messages can be done by providing a subclass with translated values in your application root module.
@NgModule({
imports: [MatStepperModule],
providers: [
{provide: MatStepperIntl, useClass: MyIntl},
],
})
export class MyApp {}
The stepper is treated as a tabbed view for accessibility purposes, so it is given role="tablist"
by default. The header of step that can be clicked to select the step is given role="tab"
, and the content that can be expanded upon selection is given role="tabpanel"
. aria-selected
attribute of step header and aria-expanded
attribute of step content is automatically set based on step selection change.
The stepper and each step should be given a meaningful label via aria-label
or aria-labelledby
.