Lists

Lists are continuous, vertical indexes of text or images.

Lists are a continuous group of text or images. They are composed of items containing primary and supplemental actions, which are represented by icons and text.

Introduction

Lists present information in a concise, easy-to-follow format through a continuous, vertical index of text or images.

Material UI Lists are implemented using a collection of related components:

List: a wrapper for list items. Renders as a <ul> by default.
List Item: a common list item. Renders as an <li> by default.
List Item Button: an action element to be used inside a list item.
List Item Icon: an icon to be used inside of a list item.
List Item Avatar: an avatar to be used inside of a list item.
List Item Text: a container inside a list item, used to display text content.
List Divider: a separator between list items.
List Subheader: a label for a nested list.

The last item of the previous demo shows how you can render a link:

<ListItemButton component="a" href="#simple-list">
  <ListItemText primary="Spam" />
</ListItemButton>

You can find a demo with React Router following this section of the documentation.

Basics

import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';

Nested List

Folder List

Photos
Jan 9, 2014
Work
Jan 7, 2014
Vacation
July 20, 2014

Interactive

Below is an interactive demo that lets you explore the visual results of the different settings:

Enable denseEnable secondary text

Text only

Single-line item
Single-line item
Single-line item

Icon with text

Single-line item
Single-line item
Single-line item

Avatar with text

Single-line item
Single-line item
Single-line item

Avatar with text and icon

Single-line item
Single-line item
Single-line item

Selected ListItem

Align list items

When displaying three lines or more, the avatar is not aligned at the top. You should set the alignItems="flex-start" prop to align the avatar at the top, following the Material Design guidelines:

Brunch this weekend?
Ali Connors — I'll be in your neighborhood doing errands this…
Summer BBQ
to Scott, Alex, Jennifer — Wish I could come, but I'm out of town this…
Oui Oui
Sandra Adams — Do you have Paris recommendations? Have you ever…

List Controls

Checkbox

A checkbox can either be a primary action or a secondary action.

The checkbox is the primary action and the state indicator for the list item. The comment button is a secondary action and a separate target.

Line item 1
Line item 2
Line item 3
Line item 4

The checkbox is the secondary action for the list item and a separate target.

Line item 1
Line item 2
Line item 3
Line item 4

Switch

The switch is the secondary action and a separate target.

Settings
Wi-Fi
Bluetooth

Sticky subheader

Upon scrolling, subheaders remain pinned to the top of the screen until pushed off screen by the next subheader. This feature relies on CSS sticky positioning.

- I'm sticky 0
- Item 0
- Item 1
- Item 2
- I'm sticky 1
- Item 0
- Item 1
- Item 2
- I'm sticky 2
- Item 0
- Item 1
- Item 2
- I'm sticky 3
- Item 0
- Item 1
- Item 2
- I'm sticky 4
- Item 0
- Item 1
- Item 2

Inset List Item

The inset prop enables a list item that does not have a leading icon or avatar to align correctly with items that do.

Chelsea Otakan
Eric Hoffman

Gutterless list

When rendering a list within a component that defines its own gutters, ListItem gutters can be disabled with disableGutters.

Line item 1
Line item 2
Line item 3

<List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
  {[1, 2, 3].map((value) => (
    <ListItem
      key={value}
      disableGutters
      secondaryAction={
        <IconButton aria-label="comment">
          <CommentIcon />
        </IconButton>
      }
    >
      <ListItemText primary={`Line item ${value}`} />
    </ListItem>
  ))}
</List>

<List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
  {[1, 2, 3].map((value) => (
    <ListItem
      key={value}
      disableGutters
      secondaryAction={
        <IconButton aria-label="comment">
          <CommentIcon />
        </IconButton>
      }
    >
      <ListItemText primary={`Line item ${value}`} />
    </ListItem>
  ))}
</List>

Press Enter to start editing

Virtualized List

In the following example, we demonstrate how to use react-window with the List component. It renders 200 rows and can easily handle more. Virtualization helps with performance issues.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

<FixedSizeList
  height={400}
  width={360}
  itemSize={46}
  itemCount={200}
  overscanCount={5}
>
  {renderRow}
</FixedSizeList>

<FixedSizeList
  height={400}
  width={360}
  itemSize={46}
  itemCount={200}
  overscanCount={5}
>
  {renderRow}
</FixedSizeList>

Press Enter to start editing

The use of react-window when possible is encouraged. If this library doesn't cover your use case, you should consider using alternatives like react-virtuoso.

Customization

Here are some examples of customizing the component. You can learn more about this in the overrides documentation page.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.