List

Introduction

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.

Basic Usage

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

function Demo() {
  return (
    <List>
      <ListItem>
        <ListItemText primary="Item 1" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 2" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 3" />
      </ListItem>
    </List>
  );
}

Simple List

A simple list with text items.

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

function SimpleList() {
  return (
    <List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      {['Inbox', 'Starred', 'Send email', 'Drafts'].map((text) => (
        <ListItem key={text} disablePadding>
          <ListItemButton>
            <ListItemText primary={text} />
          </ListItemButton>
        </ListItem>
      ))}
    </List>
  );
}

Nested List

Create nested lists using collapse and state management.

import { useState } from 'react';
import List from '@mui/material/List';
import ListItemButton from '@mui/material/ListItemButton';
import ListItemText from '@mui/material/ListItemText';
import Collapse from '@mui/material/Collapse';
import ExpandLess from '@mui/icons-material/ExpandLess';
import ExpandMore from '@mui/icons-material/ExpandMore';

function NestedList() {
  const [open, setOpen] = useState(true);

  const handleClick = () => {
    setOpen(!open);
  };

  return (
    <List
      sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}
      component="nav"
    >
      <ListItemButton onClick={handleClick}>
        <ListItemText primary="Inbox" />
        {open ? <ExpandLess /> : <ExpandMore />}
      </ListItemButton>
      <Collapse in={open} timeout="auto" unmountOnExit>
        <List component="div" disablePadding>
          <ListItemButton sx={{ pl: 4 }}>
            <ListItemText primary="Starred" />
          </ListItemButton>
        </List>
      </Collapse>
    </List>
  );
}

List with Icons

Add icons to list items using ListItemIcon.

import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemButton from '@mui/material/ListItemButton';
import ListItemIcon from '@mui/material/ListItemIcon';
import ListItemText from '@mui/material/ListItemText';
import InboxIcon from '@mui/icons-material/Inbox';
import DraftsIcon from '@mui/icons-material/Drafts';

function IconList() {
  return (
    <List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      <ListItem disablePadding>
        <ListItemButton>
          <ListItemIcon>
            <InboxIcon />
          </ListItemIcon>
          <ListItemText primary="Inbox" />
        </ListItemButton>
      </ListItem>
      <ListItem disablePadding>
        <ListItemButton>
          <ListItemIcon>
            <DraftsIcon />
          </ListItemIcon>
          <ListItemText primary="Drafts" />
        </ListItemButton>
      </ListItem>
    </List>
  );
}

List with Avatars

Use ListItemAvatar to add avatars to list items.

import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemAvatar from '@mui/material/ListItemAvatar';
import ListItemText from '@mui/material/ListItemText';
import Avatar from '@mui/material/Avatar';
import ImageIcon from '@mui/icons-material/Image';
import WorkIcon from '@mui/icons-material/Work';
import BeachAccessIcon from '@mui/icons-material/BeachAccess';

function AvatarList() {
  return (
    <List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      <ListItem>
        <ListItemAvatar>
          <Avatar>
            <ImageIcon />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Photos" secondary="Jan 9, 2024" />
      </ListItem>
      <ListItem>
        <ListItemAvatar>
          <Avatar>
            <WorkIcon />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Work" secondary="Jan 7, 2024" />
      </ListItem>
      <ListItem>
        <ListItemAvatar>
          <Avatar>
            <BeachAccessIcon />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Vacation" secondary="July 20, 2024" />
      </ListItem>
    </List>
  );
}

List with Secondary Action

Add secondary actions like checkboxes or buttons using secondaryAction prop.

import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemButton from '@mui/material/ListItemButton';
import ListItemText from '@mui/material/ListItemText';
import IconButton from '@mui/material/IconButton';
import CommentIcon from '@mui/icons-material/Comment';

function SecondaryActionList() {
  return (
    <List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      {[0, 1, 2, 3].map((value) => (
        <ListItem
          key={value}
          disablePadding
          secondaryAction={
            <IconButton edge="end" aria-label="comments">
              <CommentIcon />
            </IconButton>
          }
        >
          <ListItemButton>
            <ListItemText primary={`Line item ${value + 1}`} />
          </ListItemButton>
        </ListItem>
      ))}
    </List>
  );
}

List with Switch

Add switches to list items for toggle functionality.

import { useState } from 'react';
import List from '@mui/material/List';
import ListItem from '@mui/material/ListItem';
import ListItemText from '@mui/material/ListItemText';
import Switch from '@mui/material/Switch';

function SwitchList() {
  const [checked, setChecked] = useState(['wifi']);

  const handleToggle = (value: string) => () => {
    const currentIndex = checked.indexOf(value);
    const newChecked = [...checked];

    if (currentIndex === -1) {
      newChecked.push(value);
    } else {
      newChecked.splice(currentIndex, 1);
    }

    setChecked(newChecked);
  };

  return (
    <List sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      <ListItem
        secondaryAction={
          <Switch
            edge="end"
            onChange={handleToggle('wifi')}
            checked={checked.indexOf('wifi') !== -1}
          />
        }
      >
        <ListItemText primary="Wi-Fi" />
      </ListItem>
      <ListItem
        secondaryAction={
          <Switch
            edge="end"
            onChange={handleToggle('bluetooth')}
            checked={checked.indexOf('bluetooth') !== -1}
          />
        }
      >
        <ListItemText primary="Bluetooth" />
      </ListItem>
    </List>
  );
}

Dense Lists

Use the dense prop to reduce vertical padding.

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

function DenseList() {
  return (
    <List dense sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}>
      <ListItem>
        <ListItemText primary="Item 1" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 2" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Item 3" />
      </ListItem>
    </List>
  );
}

Subheader

Add a subheader to organize list sections.

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

function SubheaderList() {
  return (
    <List
      sx={{ width: '100%', maxWidth: 360, bgcolor: 'background.paper' }}
      subheader={<ListSubheader>Settings</ListSubheader>}
    >
      <ListItem>
        <ListItemText primary="Profile" />
      </ListItem>
      <ListItem>
        <ListItemText primary="Account" />
      </ListItem>
    </List>
  );
}

Props

List Props

Prop	Type	Default	Description
`children`	`node`	-	The content of the component.
`classes`	`object`	-	Override or extend the styles applied to the component.
`dense`	`boolean`	`false`	If true, compact vertical padding designed for keyboard and mouse input is used.
`disablePadding`	`boolean`	`false`	If true, vertical padding is removed from the list.
`subheader`	`node`	-	The content of the subheader, normally ListSubheader.
`sx`	`SxProps<Theme>`	-	The system prop for defining CSS overrides and additional styles.

ListItem Props

Prop	Type	Default	Description
`alignItems`	`'flex-start'` \| `'center'`	`'center'`	Defines the align-items style property.
`children`	`node`	-	The content of the component.
`classes`	`object`	-	Override or extend the styles applied to the component.
`dense`	`boolean`	`false`	If true, compact vertical padding designed for keyboard and mouse input is used.
`disableGutters`	`boolean`	`false`	If true, the left and right padding is removed.
`disablePadding`	`boolean`	`false`	If true, all padding is removed.
`divider`	`boolean`	`false`	If true, a 1px light border is added to the bottom.
`secondaryAction`	`node`	-	The element to display at the end of ListItem.
`sx`	`SxProps<Theme>`	-	The system prop for defining CSS overrides and additional styles.

CSS Classes

List Classes

.MuiList-root - Styles applied to the root element.
.MuiList-padding - Styles applied to the root element unless disablePadding={true}.
.MuiList-dense - Styles applied to the root element if dense={true}.
.MuiList-subheader - Styles applied to the root element if a subheader is provided.

ListItem Classes

.MuiListItem-root - Styles applied to the root element.
.MuiListItem-dense - Styles applied to the root element if dense={true}.
.MuiListItem-alignItemsFlexStart - Styles applied if alignItems="flex-start".
.MuiListItem-divider - Styles applied to the root element if divider={true}.
.MuiListItem-gutters - Styles applied to the root element unless disableGutters={true}.
.MuiListItem-padding - Styles applied to the root element unless disablePadding={true}.
.MuiListItem-secondaryAction - Styles applied to the root element if secondaryAction is provided.

Accessibility

When using lists for navigation, use component="nav" and role="navigation":

<List component="nav" aria-label="main navigation">
  {/* list items */}
</List>

Interactive Lists

For interactive list items, use ListItemButton instead of wrapping with other interactive elements:

<ListItem disablePadding>
  <ListItemButton onClick={handleClick}>
    <ListItemText primary="Click me" />
  </ListItemButton>
</ListItem>

Labeling

Provide clear labels for screen readers using aria-label or aria-labelledby:

<List aria-label="contact list">
  {/* list items */}
</List>

Inputs

Data Display

Feedback

Surfaces

Navigation

Layout

Utils

Lab

Introduction

Basic Usage

Simple List

Nested List

List with Icons

List with Avatars

List with Secondary Action

List with Switch

Dense Lists

Subheader

Props

List Props

ListItem Props

CSS Classes

List Classes

ListItem Classes

Accessibility

Navigation Lists

Interactive Lists

Labeling

Build docs developers (and LLMs) love

Inputs

Data Display

Feedback

Surfaces

Navigation

Layout

Utils

Lab

​Introduction

​Basic Usage

​Simple List

​Nested List

​List with Icons

​List with Avatars

​List with Secondary Action

​List with Switch

​Dense Lists

​Subheader

​Props

​List Props

​ListItem Props

​CSS Classes

​List Classes

​ListItem Classes

​Accessibility

​Navigation Lists

​Interactive Lists

​Labeling

Build docs developers (and LLMs) love

Introduction

Basic Usage

Simple List

Nested List

List with Icons

List with Avatars

List with Secondary Action

List with Switch

Dense Lists

Subheader

Props

List Props

ListItem Props

CSS Classes

List Classes

ListItem Classes

Accessibility

Navigation Lists

Interactive Lists

Labeling