Lists

Lists are continuous, vertical indexes of text or images.

Introduction

Joy UI provides four list-related components:

• List: A wrapper for list items (defaulting as ul).
• ListItem: A common list item (default as li).
• ListItemButton: An action element to be used inside a list item.
• ListItemDecorator: A decorator of a list item, usually used to display an icon.
• ListItemContent: A container inside a list item, used to display text content.
• ListDivider: A separator between list items.
• ListSubheader: A label for a nested list.

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.

Sizes

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

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 --ListItemDecorator-size CSS variable within the List component.

Ellipsis content

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

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.

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

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.

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 --ListItem-radius from the root List component to adjust the design consistently.

Horizontal list

To show a list in a horizontal direction, use the orientation="horizontal" 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.

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" of the active variant to visually communicate the selected state.

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.

Common examples

iOS settings

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

Gmail navigation

Inspired by Gmail's web sidenav.

Collapsible list

Inspired by Gatsby's documentation sidenav. This example uses the start action (a prop of ListItem) prop to create a collapsible button.

Navigation menu

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.

API

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

• <List />
• <ListDivider />
• <ListItem />
• <ListItemButton />
• <ListItemContent />
• <ListItemDecorator />
• <ListSubheader />