Skip to content
+

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

  • 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

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:

  • 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

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