sass-references/angular-material/material/stepper/stepper.md

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.

Stepper variants

There are two stepper variants: horizontal and vertical. You can switch between the two using the orientation attribute.

Labels

If a step's label is only text, then the label attribute can be used.

For more complex labels, add a template with the matStepLabel directive inside the mat-step.

Label position

For a horizontal mat-stepper it's possible to define the position of the label. end is the default value, while bottom will place it under the step icon instead of at its side. This behaviour is controlled by labelPosition property.

Header position

If you're using a horizontal stepper, you can control where the stepper's content is positioned using the headerPosition input. By default it's on top of the content, but it can also be placed under it.

Stepper buttons

There are two button directives to support navigation between different steps: matStepperPrevious and matStepperNext.

Linear stepper

The linear attribute can be set on mat-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.

Using a single form

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-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-stepper>
</form>

Using a different form for each step

<mat-stepper orientation="vertical" linear>
  <mat-step [stepControl]="formGroup1">
    <form [formGroup]="formGroup1">
      ...
    </form>
  </mat-step>
  <mat-step [stepControl]="formGroup2">
    <form [formGroup]="formGroup2">
      ...
    </form>
  </mat-step>
</mat-stepper>

Types of steps

Optional step

If completion of a step in linear stepper is not required, then the optional attribute can be set on mat-step.

Editable step

By default, steps are editable, which means users can return to previously completed steps and edit their responses. editable="false" can be set on mat-step to change the default.

Completed step

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.

Overriding icons

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:

Note that you aren't limited to using the mat-icon component when providing custom icons.

Controlling the stepper animation

You can control the duration of the stepper's animation using the animationDuration input. If you want to disable the animation completely, you can do so by setting the properties to 0ms.

Step States

You can set the state of a step to whatever you want. The given state by default maps to an icon. However, it can be overridden the same way as mentioned above.

In order to use the custom step states, you must add the displayDefaultIndicatorType option to the global default stepper options which can be specified by providing a value for STEPPER_GLOBAL_OPTIONS in your application's root module.

@NgModule({
  providers: [
    {
      provide: STEPPER_GLOBAL_OPTIONS,
      useValue: { displayDefaultIndicatorType: false }
    }
  ]
})

Error State

If you want to show an error when the user moved past a step that hasn't been filled out correctly, you can set the error message through the errorMessage input and configure the stepper to show errors via the showError option in the STEPPER_GLOBAL_OPTIONS injection token. Note that since linear steppers prevent a user from advancing past an invalid step to begin with, this setting will not affect steppers marked as linear.

@NgModule({
  providers: [
    {
      provide: STEPPER_GLOBAL_OPTIONS,
      useValue: { showError: true }
    }
  ]
})

Lazy rendering

By default, the stepper will render all of it's content when it's initialized. If you have some content that you want to defer until the particular step is opened, you can put it inside an ng-template with the matStepContent attribute.

Responsive stepper

If your app supports a wide variety of screens and a stepper's layout doesn't fit a particular screen size, you can control its orientation dynamically to change the layout based on the viewport.

Keyboard interaction

Keyboard shortcut	Action
Left Arrow	Focus the previous step header.
Right Arrow	Focus the next step header.
Enter	Select the focused step.
Space	Select the focused step.

Localizing labels

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 {}

Accessibility

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 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.

Prefer vertical steppers when building for small screen sizes, as horizontal steppers typically take up significantly more horizontal space thus introduce horizontal scrolling. Applications with multiple scrolling dimensions make content harder to consume for some users. See the Responsive Stepper section above for an example on building a stepper that adjusts its layout based on viewport size.

Forms

Steppers often contain forms and form controls. If validation errors inside of a stepper's form prevents moving to another step, make sure that your form controls communicate error messages to assistive technology. This helps the user know why they can't advance to another step. You can accomplish this by using <mat-error> with <mat-form-field>, or by using an ARIA live region.

When a step contains a forms validation error, MatStepper will display the error in the step's header if specified. See the Error State section for an example of a stepper with an error message. For non-linear steppers, you should use an ARIA live region to announce error messages when users navigate away from a step with an error message.