List

Overview

A list is a column of rows that share a structure. Every row reads as a tuple of three slots: a leading visual (avatar, icon, radio), a content column (title, optionally supporting text), and a trailing cell (a metric, a chevron, a toggle, or nothing). The slots are the contract; what fills them changes per surface.

Anatomy

Five named parts inside the row, plus the section header that groups rows above it. The slots are optional in pairs — leading + trailing can both be absent — but the title is required. Without a title the row has nothing to read.

Content

Three content shapes cover almost every surface. Pick the lightest shape that carries the meaning — single-line where the metric and label work together, two-line where the row needs context, two-line + chevron when the row leads somewhere.

Density

Three densities tied to typical content. Pick deliberately — density is a design decision, not a styling one. The same component at different densities tells the user something different about the page.

States

Six visible states for interactive lists. Read-only lists (an activity feed, a receipt) sit at default and never react to hover. Promote a list to interactive only when the row leads somewhere or can be selected.

Selection

Two selection patterns. Single-select uses a leading radio mark; multi-select uses a leading checkbox. The selected row inherits the discovery accent — blurple subtlest — so the eye can find it on a long list.

Sections and dividers

A section is a labelled group of rows: a date header (Today, Yesterday, the absolute date for older), a status group (Demo-ready, Building, Archived), or a category. Sections are separated by a 1 px divider with 16 px padding above and below. Group headers sit at text.secondary so they read as metadata, not content.

Empty and loading

Empty states teach the system: name what shows up here, and how the first row arrives. Loading states mirror the row's shape — a pulsing avatar, two lines of content, a trailing pill — so the layout never reflows when data lands.

Behavior

• 01Read-only by default. Most lists in the product (activity feeds, receipts, exported data) don't respond to hover. Promote a list to interactive only when the row navigates or can be selected.
• 02Whole row is the click target. When interactive, the entire row activates — not just the title. Minimum 44 px height for any interactive row to meet touch-target guidance.
• 03Trailing actions are separate. If a row needs both a primary navigation and a secondary action (kebab menu, delete), the secondary action is a button inside the trailing slot — it stops propagation so a click on the icon doesn't fire the row's navigation.
• 04Truncate, don't wrap. Title and supporting text both truncate with ellipsis. The row keeps a fixed height; long content falls off the right edge rather than expanding the row.
• 05Trailing metrics align. Currency, percentages, and counts use tabular-nums slashed-zero so the decimal point stacks down a column without column shimmer.

Accessibility

• Read-only list: use semantic <ul> / <li> elements. Screen readers announce the count and let the user step through with arrow keys.
• Navigation list: wrap each row in an <a> or <button>. The row inherits keyboard focus and Enter activation natively.
• Single-select: role="radiogroup" on the list, role="radio" + aria-checked on each row. Keyboard nav: arrow keys move and select, Tab leaves the group.
• Multi-select: standard checkbox semantics. Each row carries its own checked state; Tab moves between rows.
• Section headers use <h3> / <h4>at the page's appropriate level so screen readers can use them as landmarks.
• Roving tabindex for long interactive lists — one row carries tabindex=0, others -1. Arrow keys move the focus mark; Tab leaves the list. Skips the “tab through 300 rows” problem.
• Status carried by colour pairs with copy— the failed avatar dot is decorative; the supporting text says “Denied online payment”. A screen-reader user without colour loses nothing.

Code

The List composes from List, ListSection, and ListItem primitives in @flatpay-dk/ui. Slots are plain children — pass any node into leading / trailing.

import { List, ListSection, ListItem, Avatar } from "@flatpay-dk/ui";
import { NorthEastOutlined, SouthWestOutlined } from "@mui/icons-material";

// Read-only feed
<List>
  <ListSection label="Today">
    <ListItem
      leading={<Avatar><NorthEastOutlined /></Avatar>}
      title="Bank account"
      supporting="Transfer sent"
      trailing="€ -200,00"
      trailingTone="negative"
    />
    <ListItem
      leading={<Avatar><SouthWestOutlined /></Avatar>}
      title="Settlement account"
      supporting="Transfer received"
      trailing="€ 200,00"
      trailingTone="positive"
    />
  </ListSection>
</List>

// Navigation list
<List>
  <ListItem
    as="a"
    href="/transfers/abc"
    leading={<Avatar>…</Avatar>}
    title="Bank account"
    supporting="Today, 14:32"
    chevron
  />
</List>

// Single-select
<List role="radiogroup" aria-label="Payment method">
  <ListItem
    role="radio"
    aria-checked={method === "bank"}
    onClick={() => setMethod("bank")}
    leading={<Radio checked={method === "bank"} />}
    title="Bank account"
    supporting="ending 4242"
  />
</List>

Best practices

Lists are the workhorse layout. Small habits compound across screens.

Props

Two primitives ship: the List container and the ListItem row. Section headers are a thin wrapper component.

List

ListItem

Related