List
Angular Material List is a simple way to display a list of items, optionally with icons, avatars, or selection support. Items run from a single line to three lines with a title and secondary text, can be grouped under subheaders, and come as navigation links or as a selection list with checkboxes. BuilderKit restyles the rows, the icons and the hover state so a list matches the rest of the design system.
A navigation list is usually what fills a sidenav, where the active row stays highlighted while the page it points at is open.
Example
A basic list with an icon at the start of each row.
<mat-list>
<mat-list-item>
<mat-icon svgIcon="notebook-text" matListItemIcon />
Item 1
</mat-list-item>
<mat-list-item>
<mat-icon svgIcon="notebook-text" matListItemIcon />
Item 2
</mat-list-item>
<mat-list-item>
<mat-icon svgIcon="notebook-text" matListItemIcon />
Item 3
</mat-list-item>
</mat-list>Nav list
mat-nav-list turns rows into links, and the activated input highlights the row of the current page.
<mat-nav-list>
<a mat-list-item routerLink="." routerLinkActive [activated]="rla.isActive" #rla="routerLinkActive">
<mat-icon svgIcon="notebook-text" matListItemIcon />
<span matListItemTitle>List</span>
</a>
<a mat-list-item routerLink=".">
<mat-icon svgIcon="notebook-text" matListItemIcon />
<span matListItemTitle>List</span>
</a>
<a mat-list-item routerLink=".">
<mat-icon svgIcon="notebook-text" matListItemIcon />
<span matListItemTitle>List</span>
</a>
</mat-nav-list>Sections
The matSubheader attribute labels a group of rows, and a mat-divider separates one group from the next.
<mat-list>
<div matSubheader>Folders</div>
@for (folder of folders; track folder) {
<mat-list-item>
<mat-icon svgIcon="folder" matListItemIcon />
<div matListItemTitle>{{ folder.name }}</div>
<div matListItemLine>{{ folder.updated | date }}</div>
</mat-list-item>
}
<div matSubheader>Notes</div>
<mat-divider />
@for (note of notes; track note) {
<mat-list-item>
<mat-icon svgIcon="notebook-text" matListItemIcon />
<div matListItemTitle>{{ note.name }}</div>
<div matListItemLine>{{ note.updated | date }}</div>
</mat-list-item>
}
</mat-list>Selection list
mat-selection-list makes rows selectable; the multiple input switches between checkboxes and a single choice.
<mat-selection-list [multiple]="true">
@for (shoe of typesOfShoes; track shoe) {
<mat-list-option [value]="shoe">{{ shoe }}</mat-list-option>
}
</mat-selection-list>
<mat-selection-list [multiple]="false">
@for (shoe of typesOfShoes; track shoe) {
<mat-list-option [value]="shoe">{{ shoe }}</mat-list-option>
}
</mat-selection-list>Single line
Plain text inside mat-list-item renders a single line row.
<mat-list>
<mat-list-item>This is the title</mat-list-item>
<mat-list-item>Also the title</mat-list-item>
</mat-list>Two lines
A matListItemTitle followed by secondary text renders a two line row.
<mat-list>
<mat-list-item>
<span matListItemTitle>Title</span>
<span matListItemLine>Second line</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Title</span>
<span>Second line</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Title</span>
Second line
</mat-list-item>
</mat-list>Three lines
A second matListItemLine renders a three line row; text in a line truncates instead of wrapping.
<mat-list>
<mat-list-item>
<span matListItemTitle>Title</span>
<span matListItemLine>Second line</span>
<span matListItemLine>Third line</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Title</span>
<span matListItemLine>Second line. This line will truncate.</span>
<span>Third line</span>
</mat-list-item>
<mat-list-item>
<span matListItemTitle>Title</span>
<span matListItemLine>Second line. This line will truncate.</span>
Third line
</mat-list-item>
</mat-list>Secondary text wrapping
Setting lines="3" lets secondary text outside a title or line element wrap onto the extra lines.
<mat-list>
<mat-list-item lines="3">
<span matListItemTitle>Title</span>
<span>
Secondary line that will wrap because the list lines is explicitly set to 3 lines.
Text inside of a 'matListItemTitle' or 'matListItemLine' will never wrap.
</span>
</mat-list-item>
<mat-list-item lines="3">
<span matListItemTitle>Title</span>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est
</mat-list-item>
</mat-list>List with avatars and two lines
An avatar sits at the start of the row in a round frame and lines up with the title above the secondary line, which is the shape most contact and conversation lists take.
<mat-list>
@for (person of people; track person) {
<mat-list-item>
<div class="flex size-10 items-center justify-center rounded-full bg-neutral-a4" matListItemAvatar>
{{ person.initials }}
</div>
<span matListItemTitle>{{ person.name }}</span>
<span matListItemLine>{{ person.role }}</span>
</mat-list-item>
}
</mat-list>