Overview for list
<mat-list>
is a container component that wraps and formats a series of <mat-list-item>
. As the
base list component, it provides Material Design styling, but no behavior of its own.
List items can be constructed in two ways depending the content they need to show:
Simple lists
If a list item needs to show a single line of textual information, the text can be inserted
directly into the <mat-list-item>
element.
<mat-list>
<mat-list-item>Pepper</mat-list-item>
<mat-list-item>Salt</mat-list-item>
<mat-list-item>Paprika</mat-list-item>
</mat-list>
Multi-line lists
List items that have more than one line of text have to use the matListItemTitle
directive to
indicate their title text for accessibility purposes, in addition to the matListItemLine
directive
for each subsequent line of text.
<mat-list>
<mat-list-item>
<span matListItemTitle>Pepper</span>
<span matListItemLine>Produced by a plant</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Salt</span>
<span matListItemLine>Extracted from sea water</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Paprika</span>
<span matListItemLine>Produced by dried and ground red peppers</span>
</mat-list-item>
</mat-list>
To activate text wrapping, the lines
input has to be set on the <mat-list-item>
indicating the
number of lines of text.
The following directives can be used to style the content of a list item:
Directive | Description |
---|---|
matListItemTitle |
Indicates the title of the list item. Required for multi-line list items. |
matListItemLine |
Wraps a line of text within a list item. |
matListItemIcon |
Icon typically placed at the beginning of a list item. |
matListItemAvatar |
Image typically placed at the beginning of a list item. |
matListItemMeta |
Inserts content in the meta section at the end of a list item. |
Navigation lists
Use mat-nav-list
tags for navigation lists (i.e. lists that have anchor tags).
Simple navigation lists can use the mat-list-item
attribute on anchor tag elements directly:
<mat-nav-list>
@for (link of list; track link) {
<a mat-list-item href="..." [activated]="link.isActive">{{ link }}</a>
}
</mat-nav-list>
For more complex navigation lists (e.g. with more than one target per item), wrap the anchor
element in an <mat-list-item>
.
<mat-nav-list>
@for (link of links; track link) {
<mat-list-item [activated]="link.isActive">
<a matListItemTitle href="...">{{ link }}</a>
<button mat-icon-button (click)="showInfo(link)" matListItemMeta>
<mat-icon>info</mat-icon>
</button>
</mat-list-item>
}
</mat-nav-list>
Action lists
Use the <mat-action-list>
element when each item in the list performs some action. Each item
in an action list is a <button>
element.
Simple action lists can use the mat-list-item
attribute on button tag elements directly:
<mat-action-list>
<button mat-list-item (click)="save()">Save</button>
<button mat-list-item (click)="undo()">Undo</button>
</mat-action-list>
Selection lists
A selection list provides an interface for selecting values, where each list item is an option.
Options selected: 0
The options within a selection-list should not contain further interactive controls, such as buttons and anchors.
Multi-line lists
For lists that require multiple lines per item, annotate each line with an matListItemLine
attribute. Whichever heading tag is appropriate for your DOM hierarchy should be used
(not necessarily <h3>
as shown in the example).
<!-- two line list -->
<mat-list>
@for (message of messages; track message) {
<mat-list-item>
<h3 matListItemTitle>{{message.from}}</h3>
<p matListItemLine>
<span>{{message.subject}}</span>
<span class="demo-2"> -- {{message.content}}</span>
</p>
</mat-list-item>
}
</mat-list>
<!-- three line list -->
<mat-list>
@for (message of messages; track message) {
<mat-list-item>
<h3 matListItemTitle>{{message.from}}</h3>
<p matListItemLine>{{message.subject}}</p>
<p matListItemLine class="demo-2">{{message.content}}</p>
</mat-list-item>
}
</mat-list>
Lists with icons
To add an icon to your list item, use the matListItemIcon
attribute.
<mat-list>
@for (message of messages; track message) {
<mat-list-item>
<mat-icon matListItemIcon>folder</mat-icon>
<h3 matListItemTitle>{{message.from}}</h3>
<p matListItemLine>
<span>{{message.subject}}</span>
<span class="demo-2"> -- {{message.content}}</span>
</p>
</mat-list-item>
}
</mat-list>
Lists with meta section icons
To add a meta icon to your list item, use the matListItemMeta
directive. This allows you to display an icon or any other content in the meta section of the list item.
<mat-list>
@for (message of messages; track message) {
<mat-list-item>
<div matListItemMeta>
<mat-icon>folder</mat-icon>
</div>
<h3 matListItemTitle>{{message.from}}</h3>
<p matListItemLine>
<span>{{message.subject}}</span>
<span class="demo-2"> -- {{message.content}}</span>
</p>
</mat-list-item>
}
</mat-list>
Lists with avatars
To include an avatar image, add an image tag with an matListItemAvatar
attribute.
<mat-list>
@for (message of messages; track message) {
<mat-list-item>
<img matListItemAvatar src="..." alt="...">
<h3 matListItemTitle>{{message.from}}</h3>
<p matListItemLine>
<span>{{message.subject}}</span>
<span class="demo-2"> -- {{message.content}}</span>
</p>
</mat-list-item>
}
</mat-list>
Lists with multiple sections
Subheaders can be added to a list by annotating a heading tag with an matSubheader
attribute.
To add a divider, use <mat-divider>
.
<mat-list>
<h3 matSubheader>Folders</h3>
@for (folder of folders; track folder) {
<mat-list-item>
<mat-icon matListIcon>folder</mat-icon>
<h4 matListItemTitle>{{folder.name}}</h4>
<p matListItemLine class="demo-2"> {{folder.updated}} </p>
</mat-list-item>
}
<mat-divider></mat-divider>
<h3 matSubheader>Notes</h3>
@for (note of notes; track note) {
<mat-list-item>
<mat-icon matListIcon>note</mat-icon>
<h4 matListItemTitle>{{note.name}}</h4>
<p matListItemLine class="demo-2"> {{note.updated}} </p>
</mat-list-item>
}
</mat-list>
Accessibility
Angular Material offers multiple varieties of list so that you can choose the type that best applies to your use-case.
Navigation
You should use MatNavList
when every item in the list is an anchor that navigate to another URL.
The root <mat-nav-list>
element sets role="navigation"
and should contain only anchor elements
with the mat-list-item
attribute. You should not nest any interactive elements inside these
anchors, including buttons and checkboxes.
Always provide an accessible label for the <mat-nav-list>
element via aria-label
or
aria-labelledby
.
Selection
You should use MatSelectionList
and MatListOption
for lists that allow the user to select one
or more values. This list variant uses the role="listbox"
interaction pattern, handling all
associated keyboard input and focus management. You should not nest any interactive elements inside
these options, including buttons and anchors.
Always provide an accessible label for the <mat-selection-list>
element via aria-label
or
aria-labelledby
that describes the selection being made.
By default, MatSelectionList
displays radio or checkmark indicators to identify selected items.
While you can hide the radio indicator for single-selection via hideSingleSelectionIndicator
, this
makes the component less accessible by making it harder or impossible for users to visually identify
selected items.
Custom scenarios
By default, the list assumes that it will be used in a purely decorative fashion and thus it sets no
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.
If the list is used to present a list of non-interactive content items, then the list element should
be given role="list"
and each list item should be given role="listitem"
.