List

A List component in UI design is an interface element that displays a collection of items or data in a linear arrangement. It can display data in different formats, such as text, images, or combinations. The purpose of a list is to provide users with an organized and efficient way to access and navigate through a large amount of information. Examples of list components are drop-down menus, navigation menus, data tables, and ordered/unordered collections.

Interactive Playground

The Interactive Playground allows you to experiment with various list styles and features. Once you get the results you want, copy the HTML or React code provided and paste it into your application.

  • John Smith
  • Lucille Ball
  • Spinella Manch
HTML
React
CodeSandbox
Storybook
<ul class="neo-group-list neo-group-list--hover">
  <li class="neo-group-list__wrapper">
    <div class="neo-group-list__item">
      <span
        role="img"
        aria-label="star-icon"
        class="neo-icon-star neo-icon--small"
      >
      </span>
    </div>
    <div class="neo-group-list__item neo-group-list__item--middle">
      John Smith
    </div>
    <div class="neo-group-list__item">
      <button
        aria-label="add call"
        class="neo-btn neo-icon-btn neo-btn-circle neo-btn--default neo-btn-tertiary neo-btn-tertiary--default neo-btn-circle-tertiary--default"
        data-badge
      >
        <span class="neo-icon-call-add">
        </span>
      </button>
    </div>
  </li>
  <li class="neo-group-list__wrapper">
    <div class="neo-group-list__item">
      <span
        role="img"
        aria-label="star-icon"
        class="neo-icon-star neo-icon--small"
      >
      </span>
    </div>
    <div class="neo-group-list__item neo-group-list__item--middle">
      Lucille Ball
    </div>
    <div class="neo-group-list__item">
      <button
        aria-label="add call"
        class="neo-btn neo-icon-btn neo-btn-circle neo-btn--default neo-btn-tertiary neo-btn-tertiary--default neo-btn-circle-tertiary--default"
        data-badge
      >
        <span class="neo-icon-call-add">
        </span>
      </button>
    </div>
  </li>
  <li class="neo-group-list__wrapper">
    <div class="neo-group-list__item">
      <span
        role="img"
        aria-label="star-icon"
        class="neo-icon-star neo-icon--small"
      >
      </span>
    </div>
    <div class="neo-group-list__item neo-group-list__item--middle">
      Spinella Manch
    </div>
    <div class="neo-group-list__item">
      <button
        aria-label="add call"
        class="neo-btn neo-icon-btn neo-btn-circle neo-btn--default neo-btn-tertiary neo-btn-tertiary--default neo-btn-circle-tertiary--default"
        data-badge
      >
        <span class="neo-icon-call-add">
        </span>
      </button>
    </div>
  </li>
</ul>
<List itemType="ListItem">
  <ListItem
    actions={[
      <IconButton key="add-call" aria-label="add call" icon="call-add" shape="circle" variant="tertiary"/>
    ]}
    icon={<Icon aria-label="star-icon" icon="star"/>}
  >
    John Smith
  </ListItem>
  <ListItem
    actions={[
      <IconButton key="add-call" aria-label="add call" icon="call-add" shape="circle" variant="tertiary"/>
    ]}
    icon={<Icon aria-label="star-icon" icon="star"/>}
  >
    Lucille Ball
  </ListItem>
  <ListItem
    actions={[
      <IconButton key="add-call" aria-label="add call" icon="call-add" shape="circle" variant="tertiary"/>
    ]}
    icon={<Icon aria-label="star-icon" icon="star"/>}
  >
    Spinella Manch
  </ListItem>
</List>

Anatomy

Lists are used to select between multiple options. They may include an avatar or a person’s initials, labels, and any action items associated with the list. Lists are always stacked vertically.

List Items

List Items provide users with a groups of related options. They can be navigation items allowing the user to jump to other sections of the application, lists of contacts showing their current status and providing an easy means to connect, or any other collection of similar elements.

Image showing the anatomy of a list item, there are 5 points of interest corresponding to the different elements within the list item.

  • Container:

    The box that defines the extent of the list. All components for this item appear inside the container.

  • Avatar:

    When a person is part of the list, this is a picture of the individual or their initials.

  • Text Label:

    A description of the list item. The label should be as short as possible while providing complete details.

  • Support Body Copy:

    This is additional information that helps to further define the list item.

  • Icon:

    These represent one or more action items related to the list item, such as “place a call to the person” or “edit the item’s settings.”

List Sections

List Sections are list items that contain other items beneath. The appropriate tab index attribute should be added. List Sections are expandable to show other related options in the same list.

Image showing the anatomy of a list section, there are 4 points of interest corresponding to the different elements within the list item.

  • Container:

    The box that defines the extent of the list. All other components appear inside the container.

  • Icon:

    An icon can be added to the section if it helps to make the meaning clearer or the function more apparent.

  • Text Label:

    A description of the list item. The label should be as short as possible while providing complete details.

  • Button Actions:

    These optional icons provide additional actions to the user.

Behavior

Use a list when you need to offer multiple options and actions to the user, such as for a table of contents or an address book.

Grouped Content

Collect related list items into groups to make finding things easier.

An image of list items used to group non-data content

DO: Use list items to group non-data content together.

An image of list items used in place of table rows

DON'T: Do not use list items in place of table rows.

An image of list item dividers used to group multiple related items

DO: Use dividers to group multiple items that are related together.

An image of list item dividers being used between all items in a group

DON'T: Do not use dividers between each item.

An image of list item used with expandable grouped content

DO: Use list sections for grouped items that can be expanded or selected.

An image of list sections being used in place of form fields

DON'T: Do not use list sections in place of form fields.

Alignment

Align the left side of the container for each item in the list. Text labels and avatars are left aligned within the container. All icons are right-aligned within the container.

An image of list items with 8px of padding between them

DO: Use a minimum of 8 pixels of padding between List Sections.

An image of list items built without padding

DON'T: Do not build list sections without padding.

An image of list items all having the same width

DO: All list items belonging to the same group or container should have the same width.

An image of list items with different widths used in the same container

DON'T: Do not create list groups with different widths in a single container.

Specs

Each list item is sized with padding as shown below.

List Items
Image showing list item with sizing specs in pixels
List Sections with Actions
Image showing list section with sizing specs in pixels

Keyboard Interactions

Accessibility requires that each item on the screen is reachable using the keyboard alone. The mouse is not always an option for some users. Keyboard navigation employs the following shortcuts.

Keystrokes Interaction
Tab Moves to the next list group.
Shift + Tab Moves to the previous list group.
↑ Up Arrow and ↓ Down Arrow Moves between the items in the list. Moves directly to the actions if the item is not interactive.
← Left Arrow and → Right Arrow Moves between the buttons in the list (if there is more than one).
Enter or Spacebar Activates the selcted button from the list.
Spacebar Activates the list item and toggles the switch between on and off states.

Related Content

Components