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.

<!-- example(stepper-overview) -->

<!-- example(stepper-vertical) -->

### Labels
If a step's label is only text, then the `label` attribute can be used.
<!-- example({"example": "stepper-overview",
              "file": "stepper-overview-example.html",
              "region": "label"}) -->

For more complex labels, add a template with the `matStepLabel` directive inside the
`mat-step`.
<!-- example({"example": "stepper-editable",
              "file": "stepper-editable-example.html",
              "region": "step-label"}) -->

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

<!-- example({"example": "stepper-label-position-bottom",
              "file": "stepper-label-position-bottom-example.html",
              "region": "label-position"}) -->

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

<!-- example(stepper-header-position) -->

### Stepper buttons
There are two button directives to support navigation between different steps:
`matStepperPrevious` and `matStepperNext`.
<!-- example({"example": "stepper-label-position-bottom",
              "file": "stepper-label-position-bottom-example.html",
              "region": "buttons"}) -->

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

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

<!-- example({"example": "stepper-optional",
              "file": "stepper-optional-example.html",
              "region": "optional"}) -->


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

<!-- example({"example": "stepper-editable",
              "file": "stepper-editable-example.html",
              "region": "editable"}) -->

#### 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:

<!-- example({"example": "stepper-states",
              "file": "stepper-states-example.html",
              "region": "override-icons"}) -->

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

<!-- example(stepper-animations) -->

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

<!-- example({"example": "stepper-states",
              "file": "stepper-states-example.html",
              "region": "states"}) -->

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.

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

<!-- example(stepper-states) -->

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

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

<!-- example(stepper-errors) -->

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

<!-- example(stepper-lazy-content) -->

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

<!-- example(stepper-responsive) -->

### Keyboard interaction
| Keyboard shortcut      | Action                          |
|------------------------|---------------------------------|
| <kbd>Left Arrow</kbd>  | Focus the previous step header. |
| <kbd>Right Arrow</kbd> | Focus the next step header.     |
| <kbd>Enter</kbd>       | Select the focused step.        |
| <kbd>Space</kbd>       | 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.

```ts
@NgModule({
  imports: [MatStepperModule],
  providers: [
    {provide: MatStepperIntl, useClass: MyIntl},
  ],
})
export class MyApp {}
```

<!-- example(stepper-intl) -->

### 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](#responsive-stepper)
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](#error-state)
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.