Lists

Lists are continuous, vertical indexes of text or images.

The List component is composed of items containing primary and supplemental actions, which are represented by icons and text. Lists are optimized for reading comprehension. A list consists of a single continuous column of subdivisions called rows that contain items of content.

Basic List

A List is a wrapper for multiple ListItem elements which can behave as text, links, or buttons.

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8}>
    <List>
      <ListItem button>
        <ListItemText primary="Inbox" />
      </ListItem>
      <ListItem button>
        <ListItemText primary="Drafts" />
      </ListItem>
    </List>
    <Divider />
    <List>
      <ListItem button>
        <ListItemText primary="Trash" />
      </ListItem>
    </List>
  </Grid>
</Grid>

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8}>
    <List>
      <ListItem button>
        <ListItemText primary="Inbox" />
      </ListItem>
      <ListItem button>
        <ListItemText primary="Drafts" />
      </ListItem>
    </List>
    <Divider />
    <List>
      <ListItem button>
        <ListItemText primary="Trash" />
      </ListItem>
    </List>
  </Grid>
</Grid>

List of Links

In a simple navigational scenario, define ListItems as links be either:

Including a href prop
Including the link prop and passing a custom link component, such as from a routing library

This will allow the a to inherit the ListItem default styling. For more complex design patterns, do not supply the href or link props, and wrap ListItem children with custom components as needed.

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8} component="nav">
    <List>
      <ListItem href="#">
        <ListItemText primary="Home" />
      </ListItem>
      <ListItem href="#">
        <ListItemText primary="Products" />
        <List>
          <ListItem href="#" padding={{ left: 4 }}>
            <ListItemText primary="Whizbang" />
          </ListItem>
          <ListItem href="#" padding={{ left: 4 }}>
            <ListItemText primary="Thingamajig" />
          </ListItem>
        </List>
      </ListItem>
      <ListItem href="#">
        <ListItemText primary="Contact Us" />
      </ListItem>
    </List>
  </Grid>
</Grid>

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8} component="nav">
    <List>
      <ListItem href="#">
        <ListItemText primary="Home" />
      </ListItem>
      <ListItem href="#">
        <ListItemText primary="Products" />
        <List>
          <ListItem href="#" padding={{ left: 4 }}>
            <ListItemText primary="Whizbang" />
          </ListItem>
          <ListItem href="#" padding={{ left: 4 }}>
            <ListItemText primary="Thingamajig" />
          </ListItem>
        </List>
      </ListItem>
      <ListItem href="#">
        <ListItemText primary="Contact Us" />
      </ListItem>
    </List>
  </Grid>
</Grid>

List with Avatar Icons

This example illustrates using ListItemAvatar and Avatar to contain an icon, the secondary ListItemText prop, and use of selected on ListItem to highlight a current item.

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8} component="nav">
    <List>
      <ListItem button selected>
        <ListItemAvatar>
          <Avatar color="initial">
            <Folder />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Inbox" secondary="New messages" />
      </ListItem>
      <ListItem button>
        <ListItemAvatar>
          <Avatar color="initial">
            <Delete />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Trash" secondary="Deleted messages" />
      </ListItem>
    </List>
  </Grid>
</Grid>

<Grid container justify="center">
  <Grid item xs={12} sm={10} md={8} component="nav">
    <List>
      <ListItem button selected>
        <ListItemAvatar>
          <Avatar color="initial">
            <Folder />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Inbox" secondary="New messages" />
      </ListItem>
      <ListItem button>
        <ListItemAvatar>
          <Avatar color="initial">
            <Delete />
          </Avatar>
        </ListItemAvatar>
        <ListItemText primary="Trash" secondary="Deleted messages" />
      </ListItem>
    </List>
  </Grid>
</Grid>

List with Avatar and Multi-line Secondary Content

<List>
  <ListItem button alignItems="flex-start">
    <ListItemAvatar>
      <Avatar alt="Storm" src="https://images.prismic.io/unifi/3391b0dd-de4a-4c9d-870c-ac950f0e408e_Storm.jpg" />
    </ListItemAvatar>
    <ListItemText
      primary="Brunch this weekend?"
      secondary={
        <>
          <Typography component="span" color="textPrimary">
            Storm McGolden
          </Typography>
          {" — I'll be in your neighborhood doing errands this weekend..."}
        </>
      }
    />
  </ListItem>
  <ListItem button alignItems="flex-start">
    <ListItemAvatar>
      <Avatar alt="Neiva" src="https://images.prismic.io/unifi/28cdd998-dc75-46a7-98b5-4199d3935845_Neiva.jpg" />
    </ListItemAvatar>
    <ListItemText
      primary="Summer BBQ"
      secondary={
        <>
          <Typography component="span" color="textPrimary">
            Ms. Neiva Huskyface
          </Typography>
          {" — Let's get together and grill some burgers..."}
        </>
      }
    />
  </ListItem>
</List>

<List>
  <ListItem button alignItems="flex-start">
    <ListItemAvatar>
      <Avatar alt="Storm" src="https://images.prismic.io/unifi/3391b0dd-de4a-4c9d-870c-ac950f0e408e_Storm.jpg" />
    </ListItemAvatar>
    <ListItemText
      primary="Brunch this weekend?"
      secondary={
        <>
          <Typography component="span" color="textPrimary">
            Storm McGolden
          </Typography>
          {" — I'll be in your neighborhood doing errands this weekend..."}
        </>
      }
    />
  </ListItem>
  <ListItem button alignItems="flex-start">
    <ListItemAvatar>
      <Avatar alt="Neiva" src="https://images.prismic.io/unifi/28cdd998-dc75-46a7-98b5-4199d3935845_Neiva.jpg" />
    </ListItemAvatar>
    <ListItemText
      primary="Summer BBQ"
      secondary={
        <>
          <Typography component="span" color="textPrimary">
            Ms. Neiva Huskyface
          </Typography>
          {" — Let's get together and grill some burgers..."}
        </>
      }
    />
  </ListItem>
</List>

Data Lists

The datalist property is a structural variant for <List/> that offers three layouts intended for non-table key/value pairs.

Using datalist limits the allowed <List/> children to only <ListText> and it is expected that both a primary and secondary value are provided, where primary becomes the "key" and secondary becomes the "value".

String content or React elements can be provided to the primary or secondary prop, as is also valid in regular Lists. This allows flexibility in formatting as well as allowing icons or extra actions to be provided. Be aware that adding non-text content may create a need to resolve for any alignment side effects.

Vertical (default)

Keys and values stay in row alignment until the container width is reduced below the computed or supplied datalistBreakpoint and then the value drops below the key into stacked alignment.

Additional Properties

The following are valid only for the vertical layout.

dataKeyWidth

Value: numerical, intended to be max-allowed character width for the key.

If not passed, this is computed by looping through all list items and finding the longest key by character count.

datalistBreakpoint

Value: string, recommended to be set in rem

Determines at what total list width to break the value below the key.

If not passed, this is set to 20rem as default unless the dataKeyWidth is passed or computed to be greater than 16, in which case this is recomputed to allow more space to prevent the value column becoming far too narrow before breaking.

<List datalist>
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

<List datalist>
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

Horizontal

Values are right aligned and never wrap below the key.

<List datalist="horizontal">
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

<List datalist="horizontal">
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

Columns

Multi-column layout is applied when the container width allows, switching to stacked layout with similar appearance to vertical within narrow containers/mobile views.

<List datalist="columns">
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

<List datalist="columns">
  <ListItem>
    <ListItemText primary="Application ID" secondary="3848393" />
  </ListItem>
  <ListItem>
    <ListItemText
      primary="Address"
      secondary={
        <>
          1344 Candyland Lane
          <br />
          Lincoln, NE 67318
        </>
      }
    />
  </ListItem>
  <ListItem>
    <ListItemText primary="Start Date" secondary="Feburary 25, 2020" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Prequalified Amount" secondary="$10,000" />
  </ListItem>
  <ListItem>
    <ListItemText primary="Email" secondary="aearhardt1937@hotmail.com" />
  </ListItem>
</List>

Lists

Basic List

List of Links

List with Avatar Icons

List with Avatar and Multi-line Secondary Content

Data Lists

Vertical (default)

Additional Properties

Horizontal

Columns

Properties

<List />

<ListItem />

<ListItemText />

<ListItemAvatar />

<ListItemIcon />