diff --git a/src/lib/stepper/stepper.md b/src/lib/stepper/stepper.md new file mode 100644 index 000000000000..54e273068cf5 --- /dev/null +++ b/src/lib/stepper/stepper.md @@ -0,0 +1,132 @@ +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 components: `md-horizontal-stepper` and `md-vertical-stepper`. They +can be used the same way. The only difference is the orientation of stepper. +`md-horizontal-stepper` selector can be used to create a horizontal stepper, and +`md-vertical-stepper` can be used to create a vertical stepper. `md-step` components need to be +placed inside either one of the two stepper components. + +### Labels +If a step's label is only text, then the `label` attribute can be used. +```html + + + Content 1 + + + Content 2 + + +``` + +For more complex labels, add a template with the `mdStepLabel` directive inside the +`md-step`. +```html + + + ... + ... + + +``` + +### Stepper buttons +There are two button directives to support navigation between different steps: +`mdStepperPrevious` and `mdStepperNext`. +```html + + + ... +
+ + +
+
+
+``` + +### Linear stepper +The `linear` attribute can be set on `md-horizontal-stepper` and `md-vertical-stepper` to create +a linear stepper that requires the user to complete previous steps before proceeding +to following steps. For each `md-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. + +#### Using a single form +When using a single form for the stepper, `mdStepperPrevious` and `mdStepperNext` have to be +set to `type="button"` in order to prevent submission of the form before all steps +are completed. + +```html +
+ + + ... +
+ +
+
+ + ... +
+ + +
+
+ ... +
+
+``` + +#### Using a different form for each step +```html + + +
+ ... +
+
+ +
+ ... +
+
+
+``` +### Types of steps + +#### Optional step +If completion of a step in linear stepper is not required, then the `optional` attribute can be set +on `md-step`. + +#### Editable 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 `md-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. + +### Keyboard interaction +- LEFT_ARROW: Focuses the previous step header +- RIGHT_ARROW: Focuses the next step header +- ENTER, SPACE: Selects the step that the focus is currently on +- TAB: Focuses the next tabbable element +- TAB+SHIFT: Focuses the previous tabbable element + +### 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 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`. \ No newline at end of file