Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    ListItem

    One row of a list: a leading visual, a title and subtitle, and meta or an action at the end.

    Storybook
    Storybook
    Source
    Source

    When to use

    Section titled “When to use”

    ListItem is for repeated rows with the same structure: a settings menu, a list of people, notifications, files in a folder. Each row describes one topic at a glance and often leads to one place.

    When not to use

    Section titled “When not to use”
    • For records to compare: use Table or DataTable when you need columns and sorting.
    • For rich content: use Card for content with several sections and actions; do not put each row in its own card.
    • For navigation tabs: use Tabs to switch between views of the same page.
    • To pick an option: use Select, RadioGroup or Checkbox to choose a value; ListItem carries no selection state.

    Anatomy

    Section titled “Anatomy”
    1. List (ListItem.List): a <ul>; optional dividers (divided) and an entrance motion (animate).
    2. Root: an <li> inside the list and a <div> outside it. It carries size, selected and disabled as data attributes.
    3. Row: an 8 px rounded box inside the root. With render, the link or button is this box.
    4. Leading (ListItem.Leading): an avatar, an icon or a thumbnail.
    5. Content (ListItem.Content): the title (ListItem.Title) and the subtitle (ListItem.Subtitle).
    6. Meta (ListItem.Meta): short information such as a date or a count.
    7. Trailing (ListItem.Trailing): a badge, an icon or a separate button.

    Behaviour

    Section titled “Behaviour”
    • A row is static by default; there is no interaction.
    • With render the row is one target. On hover, press and focus the colour is tinted; nothing moves.
    • selected marks the current row: a surface, a bar at the inline start and aria-current="true". Use a button row for navigation, not as a toggle.
    • By default the title shows one line and the subtitle two, then an ellipsis. truncate keeps both on one line. Keep titles short so nothing important is cut.
    • In an interactive row, do not put a link or a button in trailing. When you need a separate action, keep the row static and add a Button.

    Guidelines

    Section titled “Guidelines”

    One row, one target

    Section titled “One row, one target”

    When the whole row opens one place, it should hold no other action. For a separate action, keep the row static.

    • Settings
    DoThe row is static; edit is a separate button.
    Don'tA second button inside a clickable row: nested interactive elements.

    Short title, detail in the subtitle

    Section titled “Short title, detail in the subtitle”

    The title names the row; move detail to the subtitle.

      NotificationsEmail and app
    DoA short title, the detail in the subtitle.
      Notifications, email and app notifications and quiet hours
    Don'tAll the detail is in the title.

    One kind of visual at the start

    Section titled “One kind of visual at the start”

    Rows in one list use the same kind of leading visual.

    • User 1
    • User 2
    DoAn Avatar in every row.
    • User 1
    • User 2
    Don'tAvatar and icon mixed: the titles fall out of line.

    Content

    Section titled “Content”
    • Write the title as a noun phrase in sentence case: “Notifications”, “Account settings”.
    • Make the subtitle a one-sentence detail that does not repeat the title.
    • Keep meta short: “Today”, “3 new”.
    • The link text of a row is the title itself; never “Click here”.
    • Mark the Avatar of a person whose name is the title decorative, so the name is not read twice.
    Section titled “Related components”
    • Avatar: the person or company picture at the start of a row.
    • Card: for rich content and actions.
    • Button: for the separate action of a row.
    • Icon: for a symbol at the start or end of a row.