List

Usage

import {
  List,
  ListItem,
  ListItemContent,
  ListItemLeading,
  ListItemSubline,
  ListItemTitle,
  ListItemTrailing,
} from '@epilot/spark-ui/list'

function DocumentList() {
  return (
    <List>
      <ListItem render={<a href="/documents/1" />}>
        <ListItemLeading>
          <Icon name="edit_square" size="medium" variant="ghost" />
        </ListItemLeading>
        <ListItemContent>
          <ListItemTitle>Installation report</ListItemTitle>
          <ListItemSubline>Signed 3 May 2026</ListItemSubline>
        </ListItemContent>
        <ListItemTrailing>
          <MaterialSymbol name="chevron_right" />
        </ListItemTrailing>
      </ListItem>
    </List>
  )
}

List is fully headless: it renders row layout and neutral container chrome, but every row is composed from the parts above, so it fits documents, devices, meter readings, or a settings menu equally well. Pass render={<a href/>} or render={<button/>} on a ListItem to make that row interactive; leave it off for a static row (a value display, a heading row).

Use List for a vertical stack of records where every row shares the same shape. Reach for Accordion when each row's content expands/collapses in place, and Base UI's Menu (see Dropdown Menu) when you need a real ARIA dropdown menu of actions. List does not implement menu semantics.

Examples

Variants

Container chrome is set with the variant prop (default soft). All variants are neutral (never accent) and scale with the spacing / scaling knobs.

Nested and external rows

A chevron_right trailing icon signals a row that navigates deeper (a nested settings screen); open_in_new signals a row that leaves the app. Both are just a MaterialSymbol in ListItemTrailing: the icon is a convention, not a prop.

Two-column value rows

ListItemContent can appear twice in one row: a left column for identity, a right column (align="end") for a value. Color the delta text yourself. The component has no opinion on positive/negative.

Row with an action

When a row carries an action (e.g. add, remove), put a Button in ListItemTrailing and keep the row itself static. Don't also make it interactive, or you nest an action inside a clickable row. The button supplies its own accent; the row stays neutral.

Full row anatomy

Every slot at once: a leading icon, a start column and an align="end" column that each stack a ListItemPreline, ListItemTitle, and ListItemSubline, plus a trailing chevron.

Selectable rows

Selection is consumer-managed: put a Checkbox (or Radio) in ListItemLeading and wire it up like any other form control. Associate it with the row's title via aria-labelledby so screen readers announce a label, not just "checkbox".

Loading state

Pass skeleton on a ListItem for a loading placeholder row. Skeleton rows are aria-hidden, so don't mix them with real rows the user can already interact with.

Navigation menu

A settings or profile "menu" is just a List of interactive rows: nested items get a chevron_right, external ones get open_in_new, and separate groups are separate Lists. There is no dedicated menu component: this navigation pattern is the List. Reach for Base UI's Menu only when you need a floating dropdown of actions with roving-focus keyboard semantics.

API Reference

List

Renders a <ul role="list">; the role is explicit because Safari drops list semantics once list-style: none is applied. Spacing and corner radius follow the ambient spacing/scaling/radius knobs; variant does not.

ListItem

The row is a hard 44px minimum height (WCAG 2.5.5) regardless of the spacing/scaling knobs; padding and text size still scale past that floor. Interactive-row hover/focus tint and the ListItemTrailing accent-on-hover both key off whether render is set (there is no separate interactive prop).

ListItemContent

A ListItem can hold more than one ListItemContent (see Two-column value rows above); each one is an independent flex column, so they lay out side by side.

Leaf parts

ListItemLeading, ListItemPreline, ListItemTitle, ListItemSubline, and ListItemTrailing are unstyled-beyond-typography wrappers (div/span): they exist to give each part of a row a consistent slot and font treatment (title is bold, preline/subline are muted gray-11), not to enforce a fixed row shape. All forward className and every other prop for their underlying element, so any HTML attribute (an id for aria-labelledby, an onClick) passes straight through.

ListItemTrailing's accent-on-hover tint works by setting a text color on the wrapper and relying on the child to inherit it via currentColor. MaterialSymbol does this correctly, but the color-independent Icon component (which hardcodes its own ink) will not visually respond. Use MaterialSymbol for the trailing affordance, not Icon.

Accessibility

• The list exposes role="list" and each row role="listitem" regardless of interactivity, so assistive tech always reports the count of rows.
• Interactive rows are real <a> or <button> elements via render, never a <div onClick>, so they're reachable by keyboard, get a visible focus ring, and are announced with their native role.
• The recent dot is decorative (aria-hidden); don't rely on it alone to convey "new"; pair it with text if that state must be announced.
• List does not implement menu, listbox, or combobox semantics. If you need arrow-key navigation and a menu/menuitem role tree (a dropdown of actions), use Base UI's Menu (see Dropdown Menu for the Spark-themed wrapper).
• Selection controls (Checkbox, Radio) in ListItemLeading are your responsibility to label: use aria-labelledby pointing at the row's ListItemTitle id, as shown in Selectable rows.