Skip to content

Commit 5c87a84

Browse files
jelbournjosephperrott
authored andcommitted
docs(list): expand accessibility section (#9443)
1 parent ef78a97 commit 5c87a84

File tree

1 file changed

+17
-1
lines changed

1 file changed

+17
-1
lines changed

src/lib/list/list.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,8 +152,24 @@ To add a divider, use `<mat-divider>`.
152152
```
153153

154154
### Accessibility
155+
The type of list used in any given situation depends on how the end-user will be interacting with
156+
the it.
157+
158+
#### Navigation
159+
When the list-items navigate somewhere, `<mat-nav-list>` should be used with `<a mat-list-item>`
160+
elements as the list items. The nav-list will be rendered using `role="navigation"` and can be
161+
given an `aria-label` to give context on the set of navigation options presented. Additional
162+
interactive content, such as buttons, should _not_ be added inside the anchors.
163+
164+
#### Selection
165+
When the list is primarily used to select one or more values, a `<mat-selection-list>` should be
166+
used with `<mat-list-option>`, which map to `role="listbox"` and `role="option"`, respectively. The
167+
list should be given an `aria-label` that describes the value or values being selected. Each option
168+
should _not_ contain any additional interactive elements, such as buttons.
169+
170+
#### Custom scenarios
155171
By default, the list assumes that it will be used in a purely decorative fashion and thus sets no
156-
roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of <div>
172+
roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of `<div>`
157173
elements on the page. Any interactive content within the list should be given an appropriate
158174
accessibility treatment based on the specific workflow of your application.
159175

0 commit comments

Comments
 (0)