toc

Lists

Lists are continuous, vertical indexes of text and images, with optional selection, reordering, expanding and swipe actions.

View as Markdown

celebration Festivals Food, music, arts, community May 8

palette Arts Literature, games, music May 12

groups Family and friends The relationships that bring and bind May 20

<md-gb-list segmented>
  <md-gb-list-item>
    <md-gb-icon slot="leading">celebration</md-gb-icon>
    Festivals
    <span slot="supporting-text">Food, music, arts, community</span>
    <span slot="trailing-text">May 8</span>
  </md-gb-list-item>
  <md-gb-list-item>
    <md-gb-icon slot="leading">palette</md-gb-icon>
    Arts
    <span slot="supporting-text">Literature, games, music</span>
    <span slot="trailing-text">May 12</span>
  </md-gb-list-item>
  <md-gb-list-item>
    <md-gb-icon slot="leading">groups</md-gb-icon>
    Family and friends
    <span slot="supporting-text">The relationships that bring and bind</span>
    <span slot="trailing-text">May 20</span>
  </md-gb-list-item>
</md-gb-list>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-list.json (setup)

Usage guidelines

Link to “Usage guidelines”

Make items easy to scan. Keep labels short, order items in a logical way such as alphabetical or numerical, and show icons, text and actions in a consistent format.
Choose a style. A standard list is flat; a segmented list separates each item into its own container.
Match the item to its content. Add supporting text, an overline, an avatar or a leading icon to describe what an item is.
Add behavior when it helps. Lists can select, reorder, expand and reveal swipe actions.

Anatomy

Link to “Anatomy”

A list holds list items. Each item has a label and slots around it.

mail

Inbox Ada Lovelace Notes on the engine 9:41 AM

star

<md-gb-list aria-label="Messages">
  <md-gb-list-item>
    <div slot="avatar">A</div>
    <md-gb-icon slot="leading">mail</md-gb-icon>
    <span slot="overline">Inbox</span>
    Ada Lovelace
    <span slot="supporting-text">Notes on the engine</span>
    <span slot="trailing-text">9:41 AM</span>
    <md-gb-icon slot="trailing">star</md-gb-icon>
  </md-gb-list-item>
</md-gb-list>

Examples

Link to “Examples”

Slots

Link to “Slots”

An item's label is its default slot. Put an md-gb-icon in leading, a circular image or initial in avatar, a small line above the label in overline, and more detail in supporting-text.

mail

Inbox Weekly digest Your summary for the last seven days 9:41 AM

mail

Inbox Trip itinerary Flights, hotel and reservations Yesterday

<md-gb-list>
  <md-gb-list-item>
    <md-gb-icon slot="leading">mail</md-gb-icon>
    <span slot="overline">Inbox</span>
    Weekly digest
    <span slot="supporting-text">Your summary for the last seven days</span>
    <span slot="trailing-text">9:41 AM</span>
  </md-gb-list-item>
  <md-gb-list-item>
    <md-gb-icon slot="leading">mail</md-gb-icon>
    <span slot="overline">Inbox</span>
    Trip itinerary
    <span slot="supporting-text">Flights, hotel and reservations</span>
    <span slot="trailing-text">Yesterday</span>
  </md-gb-list-item>
</md-gb-list>

Segmented

Link to “Segmented”

Add segmented to show each item in its own container, separated by a small gap.

Apples

Bananas

Cucumbers

<md-gb-list segmented>
  <md-gb-list-item>Apples</md-gb-list-item>
  <md-gb-list-item>Bananas</md-gb-list-item>
  <md-gb-list-item>Cucumbers</md-gb-list-item>
</md-gb-list>

Non-interactive items

Link to “Non-interactive items”

Add static to an item that only displays information, so it has no hover, focus or press states.

The first computer (ENIAC) 1946

Sputnik launched into space 1957

<md-gb-list segmented>
  <md-gb-list-item static>
    The first computer (ENIAC)
    <span slot="trailing-text">1946</span>
  </md-gb-list-item>
  <md-gb-list-item static>
    Sputnik launched into space
    <span slot="trailing-text">1957</span>
  </md-gb-list-item>
</md-gb-list>

Selection

Link to “Selection”

Add selectable to let people select several items with a long press, and by tapping while in selection mode. The list fires itemselectionchange, and selected items have checked. Add selection-primary when selecting is the main task, to always show the checkboxes.

image Beach

image Forest

image Mountains

<md-gb-list selectable segmented>
  <md-gb-list-item>
    <md-gb-icon slot="leading">image</md-gb-icon>
    Beach
  </md-gb-list-item>
  <md-gb-list-item>
    <md-gb-icon slot="leading">image</md-gb-icon>
    Forest
  </md-gb-list-item>
  <md-gb-list-item>
    <md-gb-icon slot="leading">image</md-gb-icon>
    Mountains
  </md-gb-list-item>
</md-gb-list>

Reordering

Link to “Reordering”

Add reorderable to show a drag handle on every item. People can drag it, or tap it and use the move up and move down buttons. The list fires a cancelable reorder event.

Preheat the oven

Mix the dough

Let it rise

Bake for 40 minutes

<md-gb-list reorderable segmented>
  <md-gb-list-item>Preheat the oven</md-gb-list-item>
  <md-gb-list-item>Mix the dough</md-gb-list-item>
  <md-gb-list-item>Let it rise</md-gb-list-item>
  <md-gb-list-item>Bake for 40 minutes</md-gb-list-item>
</md-gb-list>

Expandable items

Link to “Expandable items”

Add expandable to an item and put a nested md-gb-list in its nested slot. Add expanded to start open.

checklist Groceries 3 items

Bread

Milk

Eggs

<md-gb-list segmented>
  <md-gb-list-item expandable expanded>
    <md-gb-icon slot="leading">checklist</md-gb-icon>
    Groceries
    <span slot="supporting-text">3 items</span>
    <md-gb-list slot="nested" segmented>
      <md-gb-list-item>Bread</md-gb-list-item>
      <md-gb-list-item>Milk</md-gb-list-item>
      <md-gb-list-item>Eggs</md-gb-list-item>
    </md-gb-list>
  </md-gb-list-item>
</md-gb-list>

Swipe actions

Link to “Swipe actions”

Put buttons in the leading-actions and trailing-actions slots to reveal them when people swipe an item. A "more" button and the arrow keys offer the same actions without swiping.

restaurant Fresh baked breads

<md-gb-list segmented>
  <md-gb-list-item>
    <md-gb-icon slot="leading">restaurant</md-gb-icon>
    Fresh baked breads
    <button slot="leading-actions" aria-label="Pin Fresh baked breads">
      <md-gb-icon>keep</md-gb-icon>
    </button>
    <button slot="trailing-actions" aria-label="Share Fresh baked breads">
      <md-gb-icon>share</md-gb-icon>
    </button>
    <button slot="trailing-actions" aria-label="Archive Fresh baked breads">
      <md-gb-icon>archive</md-gb-icon>
    </button>
  </md-gb-list-item>
</md-gb-list>

Density

Link to “Density”

Set density on the list from 0 (default) down to -3 to remove 4px of height per step. Keep it off by default and let people opt in.

Apples

Bananas

Cucumbers

<md-gb-list density="-2" segmented>
  <md-gb-list-item>Apples</md-gb-list-item>
  <md-gb-list-item>Bananas</md-gb-list-item>
  <md-gb-list-item>Cucumbers</md-gb-list-item>
</md-gb-list>

Accessibility

Link to “Accessibility”

A list has role="list", and role="listbox" when it is selectable. Items have role="listitem". Label a list with aria-label or aria-labelledby when its purpose isn't clear from the page.
Arrow keys move between items.
In a reorderable list, the drag handle and the move up and move down buttons have labels built from the item's text, and moves are announced to screen readers. Change them with drag-handle-label, move-up-label and move-down-label when you translate the page.
Give swipe action buttons an aria-label that names the item, such as "Share Fresh baked breads".
Selecting and reordering must not need a gesture only: the checkboxes, the move buttons and the "more" button are the single-pointer alternatives.

Bread

Milk

<md-gb-list aria-label="Shopping list">
  <md-gb-list-item>Bread</md-gb-list-item>
  <md-gb-list-item>Milk</md-gb-list-item>
</md-gb-list>

Compatibility

Link to “Compatibility”

Material Design 30 uncovered90% tokens

161 of 486 buildable spec units are tested, 35 are excluded with a written reason and 0 are uncovered (the target is 0). 105 of 117 token declarations match the spec (90%), 1 differ on purpose or are being fixed, and 11 have no spec token.

lists on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Container style queries (opens in a new tab) Newly available degrades safely where it is missing
Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
Customizable <select> (opens in a new tab) Limited availability used inside an @supports guard
stretch (opens in a new tab) Limited availability used inside an @supports guard

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonListbox

Roles the component renders: button (opens in a new tab), group (opens in a new tab), list (opens in a new tab), listbox (opens in a new tab), listitem (opens in a new tab), option (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Listbox (opens in a new tab).

5 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse99 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Reduce unused JavaScript
Enable text compression
Document request latency
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-list>

Link to “<md-gb-list>”

A Material Design component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`density` The density, from 0 (default) to -3. Each step down removes 4px from the items' height (spec foundations Density: "decreasing the top and bottom padding or overall height by 4dp"). Values are clamped to that range. Like `md-gb-segmented-button-set`'s `density`.	`density`	`ListDensity`
`reorderable` Whether the items can be reordered. Shows a drag handle on every item.	`reorderable`	`boolean`	`false`
`reorderMessages` The screen reader announcements made while reordering.		`ListReorderMessages`	`LIST_REORDER_MESSAGES`
`segmented` Whether to render the list with segmented items.	`segmented`	`boolean`	`false`
`selectable` Whether the user can select several items with a long press (and drag), and by tapping them while in selection mode.	`selectable`	`boolean`	`false`
`selectionPrimary` Whether selecting is the list's primary activity: a `selectable` list then always shows the selection checkboxes (on desktop).	`selection-primary`	`boolean`	`false`

Slots

Link to “Slots”

Slot	Description
default	Used to display list items.

Events

Link to “Events”

Event	Description
`itemselectionchange` Event	When the user changes the selected items of a `selectable` list (`ListSelectionChangeEvent` with `selected`).
`reorder` Event	When the user drops an item at a new position (`ListReorderEvent` with `from`, `to` and `item`). Cancelable.

CSS parts

Link to “CSS parts”

Part	Description
`::part(drop-zone)`	The drop target shown while dragging.
`::part(list)`	The list's root element.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-shape`
`--gap`

<md-gb-list-item>

Link to “<md-gb-list-item>”

A Material Design component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`checked` Whether the list item is selected.	`checked`	`boolean`	`false`
`disabled` Whether the list item is disabled.	`disabled`	`boolean`	`false`
`dragging` Whether the item is being dragged. Set by the list while reordering.	`dragging`	`boolean`	`false`
`dragHandleLabel` The accessible label prefix of the drag handle; the item's label text is appended (e.g. "Reorder Apples").	`drag-handle-label`	`string`	`"Reorder"`
`expandable` Whether the item expands to reveal the content in its `nested` slot. Expandable items are always interactive.	`expandable`	`boolean`	`false`
`expanded` Whether an `expandable` item is expanded.	`expanded`	`boolean`	`false`
`grabbed` Whether the item is grabbed for reordering without dragging (with the keyboard or a tap on the drag handle). Set by the list; shows the move up and move down buttons.	`grabbed`	`boolean`	`false`
`moveDownLabel` The accessible label prefix of the move down button; the item's label text is appended.	`move-down-label`	`string`	`"Move down"`
`moveUpLabel` The accessible label prefix of the move up button; the item's label text is appended (e.g. "Move up Apples").	`move-up-label`	`string`	`"Move up"`
`nonInteractive` Whether the list item is non-interactive.	`static`	`boolean`	`false`
`noRevealButton` Hides the "more" button that reveals the swipe actions with a tap. Only set it when the app offers another single-pointer way to reach them (e.g. a menu), as the spec requires one.	`no-reveal-button`	`boolean`	`false`
`reorderable` Whether to show a drag handle to reorder the item within its `md-gb-list`. Set by the list when the list is `reorderable`.	`reorderable`	`boolean`	`false`
`revealButtonLabel` The accessible label prefix of the "more" button; the item's label text is appended (e.g. "More actions Apples").	`reveal-button-label`	`string`	`"More actions"`
`revealed` The side whose swipe actions are revealed, or `''` when closed.	`revealed`	`ListItemRevealed`	`""`
`rovingTabIndex` Set by a parent `md-gb-list` to make the list a single tab stop with arrow-key navigation (roving tabindex, lists.md Keyboard navigation): `0` on the list's tab stop, `-1` on the other items, `null` (default) for an item outside a list. While set, the item's other controls (drag handle, "more" and move buttons, actions) leave the tab order and are reached with Left/Right.		`number`	`null`
`selectable` Whether the item shows a selection checkbox (hover, or whenever `selectionVisible`). Set by a `selectable` parent `md-gb-list`.		`boolean`	`false`
`selectionVisible` Whether the selection checkbox is always shown: the list sets it when selection is the primary activity or once an item is selected (selection.md, "Click"). Otherwise the checkbox shows on hover.	`selection-visible`	`boolean`	`false`

Slots

Link to “Slots”

Slot	Description
default	Used to display the item's primary label.
`avatar`	Used to display a circular avatar before the item's content.
`leading`	Used to display icons and content before the item's main content.
`leading-actions`	Buttons revealed by swiping toward the end.
`nested`	Nested items or content an `expandable` item reveals.
`overline`	Used to display overline text above the main label.
`supporting-text`	Used to display supporting text below the main label.
`trailing`	Used to display icons and content after the item's main content.
`trailing-actions`	Buttons revealed by swiping toward the start. The last one is the primary action.
`trailing-text`	Used to display metadata or text after the item's main content.

Events

Link to “Events”

Event	Description
`reveal-change` Event	When the user reveals or hides the swipe actions.
`toggle` Event	When the user expands or collapses an `expandable` item (`ToggleEvent`).

Methods

Link to “Methods”

Method	Description
`close` () => void	Hides the swipe actions.
`focusDragHandle` () => void	Focuses the item's drag handle, if it has one.
`focusPrimary` () => void	Focuses the item itself (its primary action), or its first control when the item is `static` or disabled. Used by `md-gb-list`'s arrow keys.
`reveal` (side: "leading"	"trailing") => void
`rowElements` () => HTMLElement[]	The item's focusable elements in visual order (start to end): leading actions, interactive `avatar`/`leading` content, the item, interactive `trailing` content, the "more" button, the move up / move down buttons, the drag handle and the trailing actions. Left/Right move through them.

CSS parts

Link to “CSS parts”

Part	Description
`::part(actions)`	The container of the revealed actions.
`::part(drag-handle)`	The reorder drag handle.
`::part(list-item)`	The list item's root element.
`::part(move-down)`	The button that moves a grabbed item down.
`::part(move-up)`	The button that moves a grabbed item up.
`::part(nested)`	The expandable region of nested content.
`::part(reveal-button)`	The "more" button that reveals the swipe actions.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--avatar-color`
`--avatar-label`
`--avatar-label-axes`
`--avatar-label-color`
`--avatar-label-tracking`
`--avatar-shape`
`--avatar-size`
`--between-space`
`--bottom-space`
`--container-color`
`--container-height`
`--container-shape`
`--density-step`	Height removed per density step (set `density` on `md-gb-list`).
`--label-text`
`--label-text-color`
`--label-text-tracking`
`--leading-icon-color`
`--leading-icon-size`
`--leading-space`
`--overline`
`--overline-axes`
`--overline-color`
`--overline-tracking`
`--supporting-text`
`--supporting-text-axes`
`--supporting-text-color`
`--supporting-text-tracking`
`--top-space`
`--trailing-icon-color`
`--trailing-icon-size`
`--trailing-space`
`--trailing-supporting-text`
`--trailing-supporting-text-axes`
`--trailing-supporting-text-color`
`--trailing-supporting-text-tracking`

Lists

Usage guidelines

Anatomy

Examples

Slots

Segmented

Non-interactive items

Selection

Reordering

Expandable items

Swipe actions

Density

Accessibility

Compatibility

API reference

<md-gb-list>

Properties

Slots

Events

CSS parts

CSS custom properties

<md-gb-list-item>

Properties

Slots

Events

Methods

CSS parts

CSS custom properties

Download & copy

Download

Copy

Customize theme