Skip to content

docs(list): expand accessibility section #9443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 18, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion src/lib/list/list.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,24 @@ To add a divider, use `<mat-divider>`.
```

### Accessibility
The type of list used in any given situation depends on how the end-user will be interacting with
the it.

#### Navigation
When the list-items navigate somewhere, `<mat-nav-list>` should be used with `<a mat-list-item>`
elements as the list items. The nav-list will be rendered using `role="navigation"` and can be
given an `aria-label` to give context on the set of navigation options presented. Additional
interactive content, such as buttons, should _not_ be added inside the anchors.

#### Selection
When the list is primarily used to select one or more values, a `<mat-selection-list>` should be
used with `<mat-list-option>`, which map to `role="listbox"` and `role="option"`, respectively. The
list should be given an `aria-label` that describes the value or values being selected. Each option
should _not_ contain any additional interactive elements, such as buttons.

#### Custom scenarios
By default, the list assumes that it will be used in a purely decorative fashion and thus sets no
roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of <div>
roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of `<div>`
elements on the page. Any interactive content within the list should be given an appropriate
accessibility treatment based on the specific workflow of your application.

Expand Down