Skip to content
Edit this page

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.

Simple List

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

function ListItemLink(props) {
  return <ListItem button component="a" {...props} />;
}

//...

<ListItemLink href="#simple-list">
  <ListItemText primary="Spam" />
</ListItemLink>;

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

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:

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

You should change the list item alignment when displaying 3 lines or more, set the alignItems prop to "flex-start".

  • Remy Sharp
    Brunch this weekend?

    Ali Connors — I'll be in your neighborhood doing errands this…

  • Travis Howard
    Summer BBQ

    to Scott, Alex, Jennifer — Wish I could come, but I'm out of town this…

  • Cindy Baker
    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.

  • Avatar n°1
    Line item 1
  • Avatar n°2
    Line item 2
  • Avatar n°3
    Line item 3
  • Avatar n°4
    Line item 4

Switch

The switch is the secondary action and a separate target.

  • Settings
  • Wi-Fi
  • Bluetooth

Pinned Subheader List

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. Unfortunately it's not implemented by all the supported browsers. It defaults to disableSticky when not supported.

    • 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
<List className={classes.root} subheader={<li />}>
  {[0, 1, 2, 3, 4].map((sectionId) => (
    <li key={`section-${sectionId}`} className={classes.listSection}>
      <ul className={classes.ul}>
        <ListSubheader>{`I'm sticky ${sectionId}`}</ListSubheader>
        {[0, 1, 2].map((item) => (
          <ListItem key={`item-${sectionId}-${item}`}>
            <ListItemText primary={`Item ${item}`} />
          </ListItem>
        ))}
      </ul>
    </li>
  ))}
</List>

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.

<List component="nav" className={classes.root} aria-label="contacts">
  <ListItem button>
    <ListItemIcon>
      <StarIcon />
    </ListItemIcon>
    <ListItemText primary="Chelsea Otakan" />
  </ListItem>
  <ListItem button>
    <ListItemText inset primary="Eric Hoffman" />
  </ListItem>
</List>

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 className={classes.root}>
  {[1, 2, 3].map((value) => (
    <ListItem key={value} disableGutters>
      <ListItemText primary={`Line item ${value}`} />
      <ListItemSecondaryAction>
        <CommentIcon color="action" />
      </ListItemSecondaryAction>
    </ListItem>
  ))}
</List>

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>

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

Customization

🎨 If you are looking for inspiration, you can check MUI Treasury's customization examples.

API