List

List

<List divided interactive>
  <List.Item
    media={<Avatar fallback="AL" size="sm" />}
    primary="Alice Liddell"
    secondary="Owner · 12 active reports"
    trailing={<Badge tone="success" variant="soft">Online</Badge>}
    href="/users/alice"
  />
  <List.Item
    media={<Avatar fallback="BO" size="sm" />}
    primary="Bob"
    secondary="Editor · last seen 3h ago"
    trailing={<Text size="sm" tone="muted">3h</Text>}
    href="/users/bob"
  />
</List>

Install: @helixui/core

import { List } from '@helixui/core'

status: stable · since: 0.2.0

Tags: rows, feed, inbox, settings

Anatomy

[ media ]  Primary text                    [ trailing ]
           Secondary muted text
──────────────────────────────────────────────────────────
[ media ]  Primary…                              [ trailing ]
           Secondary…

Layout

• display — block
• width — fill
• height — content
• intrinsicSize — fills width, rows hug content
• stackable — true
• fullBleed — false

Visual

A vertical list of rows, each with media (avatar/icon), primary + secondary text, and trailing content. Hairline dividers between rows. Hover surface (action.neutral.default at low alpha) on interactive rows.

Props

Name	Type	Default	Description
divided	boolean	false	Render a 1px border between items.
interactive	boolean	false	Add hover/focus affordance — for clickable lists.

Slots

• List.Item — media, primary, secondary, trailing slots; optional href to render as <a>

Tokens used

color.bg.action.neutral.default, color.text.primary, color.text.secondary, color.border.default, color.border.focus, radius.md, space.2, space.3, space.4, font.family.sans, font.size.sm, font.weight.medium

Accessibility

Notes

• Renders <ul><li>. Items become <a> when href is provided, otherwise plain rows.
• For selectable lists with keyboard nav, prefer Table with selection or react-aria-components GridList.

Composes with

Component	Relation	Note
Avatar	child	Common media slot.
Badge	child	Common trailing slot.
Card	parent	Often wrapped in a Card.
EmptyState	alternative	When list is empty, render EmptyState.
Table	sibling

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

inbox list

“list of conversations with avatar, name, last message, unread count”

<List>
  {threads.map(t => (
    <List.Item key={t.id}
      media={<Avatar fallback={t.initials} />}
      primary={t.name}
      secondary={t.preview}
      trailing={<Badge>{t.unread}</Badge>}
    />
  ))}
</List>

Related

• Table