Skip to content

Lists

Lists are continuous, vertical indexes of text or images.

Introduction

Joy UI provides four list-related components:

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

Playground

Component

After installation, you can start building with this component using the following basic elements:

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

export default function MyApp() {
  return (
    <List aria-label="basic-list">
      <ListItem>Hello, world!</ListItem>
      <ListItem>Bye bye, world!</ListItem>
    </List>
  );
}

Basic usage

Use the List and ListItem components to create a basic, non-interactive, list. Make sure to use a meaningful name that describe the content of the list in the aria-labelledby prop.

Ingredients
  • 1 red onion
  • 2 red peppers
  • 120g bacon

Sizes

Use the size prop to control font-size and general list density.

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

Decorator

Use the ListItemDecorator component to add supporting icons or elements to the list item.

It comes with a minimum set width that you can adjust via the --List-decorator-size CSS variable within the List component.

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

Ellipsis content

When dealing with long content, use the ListItemComponent together with <Typography noWrap> to show ellipsis.

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

The ListDivider component comes with four inset patterns:

  • Default (without providing the inset prop): stretches from edge to edge of the list.
  • inset="gutter": from the start of the decorator to the end of the content.
  • inset="startDecorator": from the start of the decorator to the end of the list.
  • inset="startContent": from the start of the content to the end of the list.
(default)
  • Mabel Boyle
  • Boyd Burt
inset="gutter"
  • Mabel Boyle
  • Boyd Burt
inset="startDecorator"
  • Mabel Boyle
  • Boyd Burt
inset="startContent"
  • Mabel Boyle
  • Boyd Burt

For horizontal list, only inset="gutter" works on list divider.

  • Mabel Boyle
  • Boyd Burt
  • Adam Tris

Sticky item

To have a sticky list item, use a List as a child of the Sheet component. Then, on the item you wish to stick, add the sticky prop.

The Sheet component automatically adjusts the sticky list item to have the same background so that the content does not overflow when scroll. It works by default on both light and dark modes.

  • 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

Use the nested prop, within the ListItem component, to create a nested list. Note that layout and spacing of the nested list remain intact, as if it isn't nested.

The nested list inherits the list size and a few other CSS variables, such as --List-radius and --List-item-radius from the root List component to adjust the design consistently.

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

Horizontal list

To show a list in a horizontal direction, use the row prop on the List component.

Changing the semantic element

To control which HTML tag should be rendered in a given, one-off, situation, use the component prop.

<List component="ol">

Non-list

In the example below, we're rendering a List as a HTML <nav> element.

Actionable

To make a list item interactive, use ListItemButton inside a ListItem.

Secondary action

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

  • Item 1
  • Item 2

The ListItemButton and the secondary action render as siblings, that way, the semantic rendered element is appropriately adjusted.

<ul>                    {/* List */}
  <li>                  {/* ListItem */}
    <div role="button"> {/* ListItemButton */}
    <button>            {/* IconButton */}

Selected

Use the selected prop to signal whether a ListItemButton is selected or not. It applies color="primary" and a few extra styles (e.g. font weight) to visually communicate the selected state.

  • Home
  • Apps
  • Settings

CSS variables

Play around with all the CSS variables available in the list component to see how the design changes.

You can use those to customize the component on 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 web sidenav.

  • Inbox

    1,950

  • Starred
  • Categories
    • Social

      4,320

    • Updates

      22,252

Collapsible list

Inspired by Gatsby's documentation sidenav. This example uses the start action (a prop of ListItem) 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.