# Lists

> Continuous vertical indexes of text and images.

## Anatomy

A `.list` is a vertical index. Use it so people can find an item and act on it. There is no JavaScript — the HTML is the component. Order items logically, keep each row short, and put icons, text, and actions in the same place on every row.

The leading visual is the first icon, `<img>`, or `<input>`. The trailing action is the last icon, `<kbd>`, `<button>`, `<time>`, or `.meta`. A following `<p>` is supporting text. Mark the current row with `active` or `selected` — **not** `aria-selected`, which is not valid on a plain `listitem`. It needs a role (`option`, `tab`, `row`, `treeitem`), and each of those brings a keyboard contract with it.

Two variants: **standard** (the default) and `segmented`.

## Standard

Transparent rows. The selected item is a pill in `secondary-container`. The leading icon fills when the row is selected.

-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C

```
<ul class="list">
  <li>
    <span class="material-symbols" aria-hidden="true">star</span>
    List item
    <kbd>⌘C</kbd>
  </li>
  <li class="selected">
    <span class="material-symbols" aria-hidden="true">star</span>
    List item
    <kbd>⌘C</kbd>
  </li>
</ul>
```

## Segmented

Add `segmented`. Every row is a rounded tile; the selected tile uses the same `secondary-container` fill. Use this when the list itself should read as a group.

-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C
-   List item ⌘C

```
<ul class="list segmented">
  <li class="selected">
    <span class="material-symbols" aria-hidden="true">star</span>
    List item
    <kbd>⌘C</kbd>
  </li>
</ul>
```

## Text

A row can be a single line of label text, or a label with supporting text underneath. Either can wrap, or take `truncate` to ellipsis.

-   Label text only
-   A long label that will not wrap past the end of the row and is cut off
-   Headline
    
    Supporting text sits under the label and can wrap onto another line.
    

```
<li>Label text only</li>
<li><span class="truncate">A long label…</span></li>
<li>
  Headline
  <p>Supporting text sits under the label.</p>
</li>
```

## Icons

A leading icon is a quick visual cue for the label. A trailing icon is status or an action — more, info, chevron.

-   Inbox
-   Sent
-   Trash

```
<li>
  <span class="material-symbols" aria-hidden="true">inbox</span>
  Inbox
  <span class="material-symbols" aria-hidden="true">chevron_right</span>
</li>
```

## Avatars and images

A leading `.circle` is a 40dp avatar. A bare `<img>` is a 56dp thumbnail.

-   Ada Lovelace
    
    Mathematician
    
-   Icon avatar
-   Thumbnail
    
    56dp image, 8dp corners.
    

```
<li>
  <img src="portrait.jpg" alt="" class="circle">
  Ada Lovelace
  <p>Mathematician</p>
</li>
```

## Links and selection

Wrap the row in an `<a>` or `<label>` to make the whole item the target. `aria-current` on the link, or a checked radio inside the label, paints the selected pill.

-   Inbox
-   Starred
-   Snoozed

```
<li>
  <a href="/inbox" aria-current="page">
    <span class="material-symbols" aria-hidden="true">inbox</span>
    Inbox
  </a>
</li>
```

Colour

-    Red
-    Green
-    Blue

```
<fieldset>
  <legend>Colour</legend>
  <ul class="list">
    <li>
      <label>
        <input type="radio" name="color">
        Red
      </label>
    </li>
  </ul>
</fieldset>
```

## Tokens

Set these on the list (or on `:root`):

| Token | Default |
| --- | --- |
| `--md-comp-list-item-height` | 56px |
| `--md-comp-list-item-two-line-height` | 72px |
| `--md-comp-list-item-padding` | 16px |
| `--md-comp-list-item-shape` | 100px (20px segmented) |
| `--md-comp-list-item-container-color` | transparent |
| `--md-comp-list-selected-container-color` | `--md-sys-color-secondary-container` |
| `--md-comp-list-leading-icon-size` | 24px |
| `--md-comp-list-segmented-gap` | 2px |