Skip to content
+

Lists

Lists are organizational tools that enhance the readability and organization of content.

Introduction

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

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

  • Home
  • Orders
<List>
  <ListItem>
   <ListItemButton>
     <ListItemDecorator><Home /></ListItemDecorator>
     <ListItemContent>Home</ListItemContent>
     <KeyboardArrowRight />
   </ListItemButton>
  </ListItem>
</List>

Playground


Basics

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

Customization

Variants

The List component supports Joy UI's four global variants: solid, soft, outlined, and plain.

Sizes

The List component comes in three sizes: sm, md, and lg. The size of the List determines its font size and density.

size="sm"
  • Home
  • Projects
  • Settings
size="md"
  • Home
  • Projects
  • Settings
size="lg"
  • Home
  • Projects
  • Settings

Colors

Every palette included in the theme is available via the color prop.

Decorators

import ListItemDecorator from '@mui/joy/ListItemDecorator';

Use the List Item Decorator component to add supporting icons or elements to the list item.

Ingredients
  • 🧅 1 red onion
  • 🍤 2 Shrimps
  • 🥓 120g bacon

Horizontal list

Use the orientation="horizontal" prop on the List component to display the List horizontally.

Semantic elements

Use the component prop to control which HTML tag is rendered.

<List component="ol">

The example below renders the List component as an HTML <nav> element.

Marker

Use the marker prop with any valid list-style-type value to add a marker to the list items.

  • The Shawshank Redemption
  • Star Wars
    • Episode I – The Phantom Menace
    • Episode II – Attack of the Clones
    • Episode III – Revenge of the Sith
  • The Lord of the Rings: The Two Towers

Ellipsis content

import ListItemContent from '@mui/joy/ListItemContent';

When working with longer content in a List, you can use the List Item Content component in combination with <Typography noWrap /> to display an ellipsis when the content exceeds the available space. This can help to keep the List Items visually consistent and prevent text from overflowing outside of the List Item's container.

Inbox
  • Brunch this weekend?

    I'll be in your neighborhood doing errands this Tuesday.

  • Summer BBQ

    Wish I could come, but I'm out of town this Friday.

Divider

import ListDivider from '@mui/joy/ListDivider';

The List Divider component comes with four inset patterns:

  • Default (no inset prop provided): stretches form one edge of the List to the other.
  • inset="gutter": from the start of List Item Decorator to the end of the content.
  • inset="startDecorator": from the start of List Item Decorator to the end of the edge of the container.
  • inset="startContent": from the start of the content to the edge of the container.
(default)
  • Mabel Boyle
  • Boyd Burt
inset="gutter"
  • Mabel Boyle
  • Boyd Burt
inset="startDecorator"
  • Mabel Boyle
  • Boyd Burt
inset="startContent"
  • Mabel Boyle
  • Boyd Burt

If you're using a horizontal list, only inset="gutter" will work as the list divider.

  • Mabel Boyle
  • Boyd Burt
  • Adam Tris

Sticky item

Use the List component as a child of the Sheet component to create "sticky" items. On the item you wish to stick, you can then add the sticky prop.

The Sheet component automatically adjusts the sticky list item to have the same background so that content does not overflow when scrolling.

  • Category 1
    • Subitem 1
    • Subitem 2
    • Subitem 3
    • Subitem 4
    • Subitem 5
    • Subitem 6
    • Subitem 7
    • Subitem 8
    • Subitem 9
    • Subitem 10
  • Category 2
    • Subitem 1
    • Subitem 2
    • Subitem 3
    • Subitem 4
    • Subitem 5
    • Subitem 6
    • Subitem 7
    • Subitem 8
    • Subitem 9
    • Subitem 10
  • Category 3
    • Subitem 1
    • Subitem 2
    • Subitem 3
    • Subitem 4
    • Subitem 5
    • Subitem 6
    • Subitem 7
    • Subitem 8
    • Subitem 9
    • Subitem 10
  • Category 4
    • Subitem 1
    • Subitem 2
    • Subitem 3
    • Subitem 4
    • Subitem 5
    • Subitem 6
    • Subitem 7
    • Subitem 8
    • Subitem 9
    • Subitem 10
  • Category 5
    • Subitem 1
    • Subitem 2
    • Subitem 3
    • Subitem 4
    • Subitem 5
    • Subitem 6
    • Subitem 7
    • Subitem 8
    • Subitem 9
    • Subitem 10

Nested list

import ListSubheader from '@mui/joy/ListSubheader';

You can create a nested list using the nested prop on a List Item. This enables you to add a List Subheader as well as a new List component as children of the List Item. The nested List will inherit its size as well as other CSS variables like --List-radius and --ListItem-radius from the root List component to keep the design consistent. The layout and spacing of the nested List will remain independent.

  • Category 1
    • Subitem 1
    • Subitem 2
  • Category 2
    • Subitem 1
    • Subitem 2

Interactive list items

import ListItemButton from '@mui/joy/ListItemButton';

To make a List Item interactive, you can use List Item Button inside a List Item.

To add a secondary action to the List Item Button, wrap it in a List Item component and then add the desired start or end action elements to it.

  • Item 1
  • Item 2

Selected

Use the selected prop on the List Item Button component to indicate whether or not an item is currently selected. When the item is selected, it applies color="primary" and a few extra styles—like font weight—to visually communicate the selected state.

  • Home
  • Apps
  • Settings

CSS variables playground

Play around with the CSS variables available to the List components to see how the design changes. You can use these to customize the components with both the sx prop and the theme.

  • Home
  • Products
  • Online people

    • Mabel Boyle
    • Boyd Burt
<List >

CSS variables


px
px
px
px
px
px
px
px

Common examples

iOS settings

This example uses nested lists to split the settings into groups.

Settings

    • MB

      Murphy Bates

      Apple ID, iCloud, Media & Purchase

    • iCloud+ Feature Updates
  • Apple TV+ Free Year Available
    • Wi-Fi

      Mars

    • Bluetooth

      On

    • Cellular

Gmail navigation

Inspired by Gmail's desktop navigation bar.

  • Inbox

    1,950

  • Starred
  • Categories
    • Social

      4,320

    • Updates

      22,252

Collapsible list

Inspired by the Gatsby documentation navbar. This example uses the startAction prop to create a collapsible button.

  • Documentation
    • Overview
  • Quick Start
  • Tutorial

    9
  • How-to Guides

    39

Inspired by the APG Navigation Menubar design pattern. This example uses a combination of horizontal and vertical lists to form the navigation menu bar.

It also supports keyboard navigation, inspired by the Roving UX technique.

Accessibility

To ensure that your List is accessible, here are some factors you should consider:

  • Use the appropriate HTML semantic element for the list (eg. ol or ul), to ensure that assistive technologies can correctly interpret the list structure.
  • Make sure to use a meaningful name that describes the content of the list in the aria-labelledby prop.
  • Use role attributes to provide additional information about the purpose of the list and its items. For example, use role="list" for the list and role="listitem" for each list item.

Anatomy

The List component is composed of a root <ul> element with one or more child <li> elements rendered by the List Item component. All components nested inside the List Item are optional. The List Divider (when present) renders an <li> with role="separator", while the List Subheader renders a <div>.

<ul class="MuiList-root">
  <li class="MuiListItem-root">
    <div class="MuiListItemButton-root" role="button">
      <span class="MuiListItemDecorator-root">
        <!-- Icon for List Item Decorator -->
      </span>
      <div class="MuiListItemContent-root">
        <!-- List Item content -->
      </div>
    </div>
  </li>
</ul>

API

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