List

Usage

import { ChevronRight, EditSquare } from '@epilot/spark-icons'
import { Icon } from '@epilot/spark-ui/icon'
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 size="medium" variant="ghost">
            <EditSquare />
          </Icon>
        </ListItemLeading>
        <ListItemContent>
          <ListItemTitle>Installation report</ListItemTitle>
          <ListItemSubline>Signed 3 May 2026</ListItemSubline>
        </ListItemContent>
        <ListItemTrailing>
          <ChevronRight />
        </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). Every variant is neutral by default and scales with the spacing / scaling knobs; pass color="accent" to tint it with the brand accent instead.

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 Spark icon 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".

A row can also carry render at the same time: mark ListItemLeading with interactive and it stays outside the rendered <a>/<button>, so a checkbox and a navigable row compose safely with independent hit targets. Unlike the trailing case above, this isn't an anti-pattern to avoid.

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. Spark icons do this correctly, but the color-independent Icon component (which hardcodes its own ink) will not visually respond. Use a Spark icon for the trailing affordance, not Icon.

ListItemLeading takes one extra prop, interactive (boolean, default false): set it when the slot holds a focusable control (Checkbox, Radio, Button) and render is literally <a href/> or <button/> — that combination is the only one where nesting the control would be invalid HTML and double-fire clicks, so it's the only one ListItem hoists the control out of. Leave it unset for decorative content (an icon): it stays inside the row, so the whole visual row — icon included — is one click/tap target. The same applies when render is something else entirely (a Card, say) — a control nested inside a non-interactive element is valid HTML either way, so there's nothing to hoist out of.

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.