2023-08-17 23:02:04 -07:00
<!-- catalog-only-start --><!-- ---
name: Lists
dirname: list
-----><!-- catalog-only-end -->
<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">
# Lists
<!--*
# Document freshness: For more information, see go/fresh-source.
2025-11-25 13:00:41 -08:00
freshness: { owner: 'lizmitchell' reviewed: '2025-11-23' }
2023-08-17 23:02:04 -07:00
tag: 'docType:reference'
*-->
<!-- no-catalog-start -->
<!-- go/md-list -->
<!-- [TOC] -->
<!-- external-only-start -->
**This documentation is fully rendered on the
[Material Web catalog ](https://material-web.dev/components/list/ )**
<!-- external-only-end -->
<!-- no-catalog-end -->
[Lists ](https://m3.material.io/components/lists )<!-- {.external} --> are continuous,
vertical indexes of text and images
</catalog-component-header-title>
<img class="hero" src="images/list/hero.webp" alt="CImage of a mobile phone screen with a Recipies page and a list recipies in a material list. The first item is Fresh baked breads with an image of someone holding bread on the left and a horizontal three dot menu on the right. Then Tacos with an image of tacos and the same three dot menu">
</catalog-component-header>
* [Design article ](https://m3.material.io/components/lists ) <!-- {.external} -->
2023-09-25 11:19:49 -07:00
* [API Documentation ](#api )
2023-08-17 23:02:04 -07:00
* [Source code ](https://github.com/material-components/material-web/tree/main/list )
<!-- {.external} -->
<!-- catalog-only-start -->
<!--
## Interactive Demo
{% playgroundexample dirname=dirname, previewHeight=600, editorHeight=600 %}
-->
<!-- catalog-only-end -->
## Usage
`<md-list>` is a container composed of `<md-list-item>` s of different types.
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/usage.html" -->
``` html
< md-list style = "max-width: 300px;" >
2023-09-26 17:27:46 -07:00
< md-list-item >
Fruits
< / md-list-item >
2023-08-17 23:02:04 -07:00
< md-divider > < / md-divider >
2023-09-26 17:27:46 -07:00
< md-list-item >
Apple
< / md-list-item >
< md-list-item >
Banana
2023-08-17 23:02:04 -07:00
< / md-list-item >
2023-09-26 17:27:46 -07:00
< md-list-item >
< div slot = "headline" > Cucumber< / div >
< div slot = "supporting-text" > Cucumbers are long green fruits that are just as long as this multi-line description< / div >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-list-item
2024-03-18 13:10:56 -07:00
type = "link"
2023-08-17 23:02:04 -07:00
href = "https://google.com/search?q=buy+kiwis&tbm=shop"
target = "_blank" >
2023-09-26 17:27:46 -07:00
< div slot = "headline" > Shop for Kiwis< / div >
< div slot = "supporting-text" > This will link you out in a new tab< / div >
< md-icon slot = "end" > open_in_new< / md-icon >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< / md-list >
```
## Icon Items
2023-09-26 17:27:46 -07:00
Icons can be slotted into list-items' `start` or `end` slot.
2023-08-17 23:02:04 -07:00
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/usage-icon.html" -->
``` html
2023-09-26 17:27:46 -07:00
< md-list style = "max-width: 300px" >
< md-list-item >
Lit
< svg slot = "start" style = "height: 24px" viewBox = "0 0 160 200" >
2023-08-17 23:02:04 -07:00
< path
2023-09-26 17:27:46 -07:00
fill = "currentColor"
d = "m160 80v80l-40-40zm-40 40v80l40-40zm0-80v80l-40-40zm-40 40v80l40-40zm-40-40v80l40-40zm40-40v80l-40-40zm-40 120v80l-40-40zm-40-40v80l40-40z"
/ >
2023-08-17 23:02:04 -07:00
< / svg >
< / md-list-item >
< md-divider > < / md-divider >
2023-09-26 17:27:46 -07:00
< md-list-item >
Polymer
< md-icon slot = "start" > polymer< / md-icon >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-divider > < / md-divider >
2023-09-26 17:27:46 -07:00
< md-list-item >
Angular
< svg slot = "start" style = "height: 24px" viewBox = "0 0 250 250" >
< polygon points = "108,135.4 125,135.4 125,135.4 125,135.4 142,135.4 125,94.5 " / >
< path
d = "M125,30L125,30L125,30L31.9,63.2l14.2,123.1L125,230l0,0l0,0l78.9-43.7l14.2-123.1L125,30z M183.1,182.6h-21.7h0
l-11.7-29.2H125h0h0h-24.7l-11.7,29.2h0H66.9h0L125,52.1l0,0l0,0l0,0l0,0L183.1,182.6L183.1,182.6z"
/ >
2023-08-17 23:02:04 -07:00
< / svg >
< / md-list-item >
< / md-list >
```
## Image Items
2023-09-26 17:27:46 -07:00
Images should be slotted into list-items' `start` slot.
2023-08-17 23:02:04 -07:00
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/usage-image.html" -->
``` html
< md-list style = "max-width: 300px;" >
2023-09-26 17:27:46 -07:00
< md-list-item >
Cat
< img slot = "start" style = "width: 56px" src = "https://placekitten.com/112/112" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-divider > < / md-divider >
2023-09-26 17:27:46 -07:00
< md-list-item >
Kitty Cat
< img slot = "start" style = "width: 56px" src = "https://placekitten.com/114/114" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-divider > < / md-divider >
2023-09-26 17:27:46 -07:00
< md-list-item >
Cate
< img slot = "start" style = "width: 56px" src = "https://placekitten.com/116/116" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< / md-list >
```
## Accessibility
2023-09-15 13:44:49 -07:00
List can have its `role` and `tabindex` set via the `role` and `tabindex`
2023-09-26 17:27:46 -07:00
attributes, and list items can have their `role` and `tabindex` set via the
`type` and `tabindex` attributes respectively.
> NOTE: List item has a limited set of `type`s that can be set on it. This is to
> ensure that your list remains accessible with all other properties and options
> presented to it. See the `ListItemType` TypeScript type exported by list item
> for the current accepted values.
2023-09-15 13:44:49 -07:00
By default these values are set to
[`role="list"` ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/list_role )<!-- {.external} -->
and `tabindex="-1"` for list, and
[`role="listitem"` ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role )<!-- {.external} -->
and `tabindex="0"` for list items.
2023-08-17 23:02:04 -07:00
## Theming
List and List Item supports
2023-09-11 09:32:19 -07:00
[Material theming ](https://github.com/material-components/material-web/blob/main/docs/theming/README.md )<!-- {.external} -->
2023-08-17 23:02:04 -07:00
and can be customized in terms of color, typography, and shape.
### List & List Item
Token | Default value
----------------------------------------------- | -------------
`--md-list-container-color` | `--md-sys-color-surface`
2024-02-15 12:59:45 -08:00
`--md-list-item-container-shape` | `--md-sys-shape-corner-none`
2023-08-17 23:02:04 -07:00
`--md-list-item-label-text-color` | `--md-sys-color-on-surface`
`--md-list-item-supporting-text-color` | `--md-sys-color-on-surface-variant`
`--md-list-item-trailing-supporting-text-color` | `--md-sys-color-on-surface-variant`
2023-09-06 11:21:49 -07:00
`--md-list-item-label-text-font` | `--md-sys-typescale-label-large-font`
`--md-list-item-supporting-text-font` | `--md-sys-typescale-body-medium-font`
`--md-list-item-trailing-supporting-text-font` | `--md-sys-typescale-label-small-font`
2023-08-17 23:02:04 -07:00
* [All List tokens ](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list.scss )
<!-- {.external} -->
* [All List Item tokens ](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss )
<!-- {.external} -->
### List & List Item Example
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/theming-list.html" -->
``` html
< style >
: root {
--md-list-container-color : #f4fbfa ;
--md-list-item-label-text-color : #161d1d ;
--md-list-item-supporting-text-color : #3f4948 ;
--md-list-item-trailing-supporting-text-color : #3f4948 ;
2023-09-06 11:21:49 -07:00
--md-list-item-label-text-font : system-ui ;
--md-list-item-supporting-text-font : system-ui ;
--md-list-item-trailing-supporting-text-font : system-ui ;
2023-08-17 23:02:04 -07:00
}
2023-09-26 17:27:46 -07:00
[ slot = "trailing-supporting-text" ] {
width : 30 px ;
text-align : end ;
}
2023-08-17 23:02:04 -07:00
< / style >
< md-list >
2023-09-26 17:27:46 -07:00
< md-list-item type = "button" >
< div slot = "headline" > Apple< / div >
< div slot = "supporting-text" > In stock< / div >
< div slot = "trailing-supporting-text" > +100< / div >
2023-08-17 23:02:04 -07:00
< / md-list-item >
2023-09-26 17:27:46 -07:00
< md-list-item type = "button" >
< div slot = "headline" > Banana< / div >
< div slot = "supporting-text" > In stock< / div >
< div slot = "trailing-supporting-text" > 56< / div >
2023-08-17 23:02:04 -07:00
< / md-list-item >
2023-09-26 17:27:46 -07:00
< md-list-item type = "button" >
< div slot = "headline" > Cucumber< / div >
< div slot = "supporting-text" > Low stock< / div >
< div slot = "trailing-supporting-text" > 5< / div >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< / md-list >
```
### Icon List Item
Token | Default value
------------------------------------ | -----------------------------------
`--md-list-item-leading-icon-color` | `--md-sys-color-on-surface-variant`
`--md-list-item-trailing-icon-color` | `--md-sys-color-on-surface-variant`
`--md-list-item-leading-icon-size` | `18px`
`--md-list-item-trailing-icon-size` | `24px`
* [All List Item tokens ](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss )
<!-- {.external} -->
### Icon List Item Example
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/theming-icon.html" -->
``` html
< style >
: root {
background-color : #f4fbfa ;
--md-list-container-color : #f4fbfa ;
2023-09-26 17:27:46 -07:00
--md-list-item-label-text-color : #161d1d ;
2023-08-17 23:02:04 -07:00
--md-list-item-leading-icon-color : #006a6a ;
--md-list-item-trailing-icon-color : #006a6a ;
--md-list-item-leading-icon-size : 20 px ;
--md-list-item-trailing-icon-size : 20 px ;
}
md-list-item . unhealthy {
--md-list-item-trailing-icon-color : #ba1a1a ;
}
< / style >
< md-list >
2023-09-26 17:27:46 -07:00
< md-list-item >
< div slot = "headline" > Eggs< / div >
< md-icon slot = "start" > egg< / md-icon >
< md-icon slot = "end" > recommend< / md-icon >
2023-08-17 23:02:04 -07:00
< / md-list-item >
2023-09-26 17:27:46 -07:00
< md-list-item class = "unhealthy" >
< div slot = "headline" > Ice Cream< / div >
< md-icon slot = "start" > icecream< / md-icon >
< md-icon slot = "end" > dangerous< / md-icon >
2023-08-17 23:02:04 -07:00
< / md-list-item >
2023-09-26 17:27:46 -07:00
< md-list-item >
< div slot = "headline" > Orange< / div >
< md-icon slot = "start" > nutrition< / md-icon >
< md-icon slot = "end" > recommend< / md-icon >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< / md-list >
```
### Avatar List Item
Token | Default value
------------------------------------------- | -------------
`--md-list-item-leading-avatar-label-color` | `--md-sys-color-on-primary-container`
2023-09-06 11:21:49 -07:00
`--md-list-item-leading-avatar-label-font` | `--md-sys-typescale-title-medium-font`
2023-08-17 23:02:04 -07:00
`--md-list-item-leading-avatar-color` | `--md-sys-color-primary-container`
`--md-list-item-leading-avatar-size` | `40px`
2024-02-15 12:59:45 -08:00
`--md-list-item-leading-avatar-shape` | `--md-sys-shape-corner-full`
2023-08-17 23:02:04 -07:00
* [All List Item tokens ](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss )
<!-- {.external} -->
### Image List Item
Token | Default value
------------------------------------- | -------------
`--md-list-item-leading-image-height` | `56px`
`--md-list-item-leading-image-width` | `56px`
2024-02-15 12:59:45 -08:00
`--md-list-item-leading-image-shape` | `--md-sys-shape-corner-none`
2023-08-17 23:02:04 -07:00
* [All List Item tokens ](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss )
<!-- {.external} -->
### Image List Item Example
<!-- no-catalog-start -->
<!-- no-catalog-end -->
<!-- catalog-include "figures/list/theming-image.html" -->
``` html
< style >
: root {
background-color : #f4fbfa ;
--md-list-container-color : #f4fbfa ;
2023-09-26 17:27:46 -07:00
--md-list-item-label-text-color : #161d1d ;
2023-08-17 23:02:04 -07:00
--md-list-item-leading-image-height : 50 px ;
--md-list-item-leading-image-width : 100 px ;
--md-list-item-leading-image-shape : 25 px ;
}
2023-10-03 09:30:45 +02:00
img {
2024-01-04 08:10:16 -08:00
width : 40 px ;
}
2023-08-17 23:02:04 -07:00
< / style >
< md-list >
< md-list-item headline = "Wide Cat" >
2023-10-03 09:30:45 +02:00
< img slot = "start" src = "https://placekitten.com/200/100" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-list-item headline = "Round kitty cat" >
2023-10-03 09:30:45 +02:00
< img slot = "start" src = "https://placekitten.com/202/101" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< md-list-item headline = "Softe cate" >
2023-10-03 09:30:45 +02:00
< img slot = "start" src = "https://placekitten.com/212/106" >
2023-08-17 23:02:04 -07:00
< / md-list-item >
< / md-list >
```
2023-09-19 21:05:08 -07:00
<!-- auto-generated API docs start -->
## API
2023-09-27 13:33:53 -07:00
2023-09-25 21:32:35 +00:00
### MdList <code><md-list></code>
2023-09-19 21:05:08 -07:00
#### Properties
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | | `ListItem[]` | `undefined` | |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
#### Methods
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| `activateNextItem` | _ None _ | `ListItem` | Activates the next item in the list. If at the end of the list, the first item will be activated. |
| `activatePreviousItem` | _ None _ | `ListItem` | Activates the previous item in the list. If at the start of the list, the last item will be activated. |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
2023-09-25 21:32:35 +00:00
### MdListItem <code><md-list-item></code>
2023-09-19 21:05:08 -07:00
#### Properties
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `disabled` | `boolean` | `false` | Disables the item and makes it non-selectable and non-interactive. |
| `type` | `type` | `string` | `'text'` | Sets the behavior of the list item, defaults to "text". Change to "link" or "button" for interactive items. |
| `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement` 's `href` resource attribute. |
| `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement` 's `target` attribute when `href` is set. |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
2025-08-21 17:32:12 +00:00
#### Methods
<!-- mdformat off(autogenerated might break rendering in catalog) -->
| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| `click` | _ None _ | `void` | |
<!-- mdformat on(autogenerated might break rendering in catalog) -->
2023-09-25 21:32:35 +00:00
#### Events
2023-09-19 21:05:08 -07:00
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Event | Type | [Bubbles ](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles ) | [Composed ](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed ) | Description |
| --- | --- | --- | --- | --- |
| `request-activation` | `Event` | Yes | Yes | Requests the list to set `tabindex=0` on the item and focus it. |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
<!-- auto-generated API docs end -->
