Skip to content

Commit 46f53ce

Browse files
jwshinjwshinjwshinjwshin
committed
feat(stepper): Add documentation for stepper (angular#6533)
* Documentation for stepper * Revision based on review + add accessibility section
1 parent 3a59825 commit 46f53ce

File tree

1 file changed

+132
-0
lines changed

1 file changed

+132
-0
lines changed

‎src/lib/stepper/stepper.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
Angular Material's stepper provides a wizard-like workflow by dividing content into logical steps.
2+
3+
Material stepper builds on the foundation of the CDK stepper that is responsible for the logic
4+
that drives a stepped workflow. Material stepper extends the CDK stepper and has Material Design
5+
styling.
6+
7+
### Stepper variants
8+
There are two stepper components: `md-horizontal-stepper` and `md-vertical-stepper`. They
9+
can be used the same way. The only difference is the orientation of stepper.
10+
`md-horizontal-stepper` selector can be used to create a horizontal stepper, and
11+
`md-vertical-stepper` can be used to create a vertical stepper. `md-step` components need to be
12+
placed inside either one of the two stepper components.
13+
14+
### Labels
15+
If a step's label is only text, then the `label` attribute can be used.
16+
```html
17+
<md-vertical-stepper>
18+
<md-step label="Step 1">
19+
Content 1
20+
</md-step>
21+
<md-step label="Step 1">
22+
Content 2
23+
</md-step>
24+
</md-vertical-stepper>
25+
```
26+
27+
For more complex labels, add a template with the `mdStepLabel` directive inside the
28+
`md-step`.
29+
```html
30+
<md-vertical-stepper>
31+
<md-step>
32+
<ng-template mdStepLabel>...</ng-template>
33+
...
34+
</md-step>
35+
</md-vertical-stepper>
36+
```
37+
38+
### Stepper buttons
39+
There are two button directives to support navigation between different steps:
40+
`mdStepperPrevious` and `mdStepperNext`.
41+
```html
42+
<md-horizontal-stepper>
43+
<md-step>
44+
...
45+
<div>
46+
<button md-button mdStepperPrevious>Back</button>
47+
<button md-button mdStepperNext>Next</button>
48+
</div>
49+
</md-step>
50+
</md-horizontal-stepper>
51+
```
52+
53+
### Linear stepper
54+
The `linear` attribute can be set on `md-horizontal-stepper` and `md-vertical-stepper` to create
55+
a linear stepper that requires the user to complete previous steps before proceeding
56+
to following steps. For each `md-step`, the `stepControl` attribute can be set to the top level
57+
`AbstractControl` that is used to check the validity of the step.
58+
59+
There are two possible approaches. One is using a single form for stepper, and the other is
60+
using a different form for each step.
61+
62+
#### Using a single form
63+
When using a single form for the stepper, `mdStepperPrevious` and `mdStepperNext` have to be
64+
set to `type="button"` in order to prevent submission of the form before all steps
65+
are completed.
66+
67+
```html
68+
<form [formGroup]="formGroup">
69+
<md-horizontal-stepper formArrayName="formArray" linear>
70+
<md-step formGroupName="0" [stepControl]="formArray.get([0])">
71+
...
72+
<div>
73+
<button md-button mdStepperNext type="button">Next</button>
74+
</div>
75+
</md-step>
76+
<md-step formGroupName="1" [stepControl]="formArray.get([1])">
77+
...
78+
<div>
79+
<button md-button mdStepperPrevious type="button">Back</button>
80+
<button md-button mdStepperNext type="button">Next</button>
81+
</div>
82+
</md-step>
83+
...
84+
</md-horizontal-stepper>
85+
</form>
86+
```
87+
88+
#### Using a different form for each step
89+
```html
90+
<md-vertical-stepper linear>
91+
<md-step [stepControl]="formGroup1">
92+
<form [formGroup]="formGroup1">
93+
...
94+
</form>
95+
</md-step>
96+
<md-step [stepControl]="formGroup2">
97+
<form [formGroup]="formGroup2">
98+
...
99+
</form>
100+
</md-step>
101+
</md-vertical-stepper>
102+
```
103+
### Types of steps
104+
105+
#### Optional step
106+
If completion of a step in linear stepper is not required, then the `optional` attribute can be set
107+
on `md-step`.
108+
109+
#### Editable step
110+
By default, steps are editable, which means users can return to previously completed steps and
111+
edit their responses. `editable="true"` can be set on `md-step` to change the default.
112+
113+
#### Completed step
114+
By default, the `completed` attribute of a step returns `true` if the step is valid (in case of
115+
linear stepper) and the user has interacted with the step. The user, however, can also override
116+
this default `completed` behavior by setting the `completed` attribute as needed.
117+
118+
### Keyboard interaction
119+
- <kbd>LEFT_ARROW</kbd>: Focuses the previous step header
120+
- <kbd>RIGHT_ARROW</kbd>: Focuses the next step header
121+
- <kbd>ENTER</kbd>, <kbd>SPACE</kbd>: Selects the step that the focus is currently on
122+
- <kbd>TAB</kbd>: Focuses the next tabbable element
123+
- <kbd>TAB</kbd>+<kbd>SHIFT</kbd>: Focuses the previous tabbable element
124+
125+
### Accessibility
126+
The stepper is treated as a tabbed view for accessibility purposes, so it is given
127+
`role="tablist"` by default. The header of step that can be clicked to select the step
128+
is given `role="tab"`, and the content that can be expanded upon selection is given
129+
`role="tabpanel"`. `aria-selected` attribute of step header and `aria-expanded` attribute of
130+
step content is automatically set based on step selection change.
131+
132+
The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.

0 commit comments

Comments
 (0)