Lists

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.

• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star 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.

• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star List item ⌘C
• star 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 Inbox chevron_right
• send Sent info
• delete Trash more_vert

<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

• person 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.

• mail Inbox
• star Starred
• snooze 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