React List component

Preview

<List>
  <List.Item>First item</List.Item>
  <List.Item>Second item</List.Item>
  <List.Item>Third item</List.Item>
</List>

Usage

Use when

Steps, instructions, or anything with an order
Feature and benefit lists
A stack of pages, files or settings to pick from (List.Row)

Avoid when

Items open a menu of choices for a field (use Select or Combobox)
Items have columns (use Table)
Items need their own surface (use Card in a Grid)

Implementation notes

Order matters? Use as="ol": the numbers come with it
Rows go in a List with marker="none" and gap="none"; one row per destination, the one you are on `selected`
Row meta is a short fact (a count, a path, a time); it sits in ink 3 at the end of the row
Keep one icon meaning per list — mixing icons reads as noise
Write items in parallel grammar; scanning depends on it
Stop nesting at two levels

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import List once, then compose its parts with dot notation.

List.Item
List.Row

The default marker — reach for it when order does not matter.

<List>
  <List.Item>First item</List.Item>
  <List.Item>Second item</List.Item>
  <List.Item>Third item</List.Item>
</List>

Examples

Numbered List

as="ol" makes the sequence real and draws the numbers.

<List as="ol">
  <List.Item>Create your account</List.Item>
  <List.Item>Configure your settings</List.Item>
  <List.Item>Start building</List.Item>
</List>

Icon List

Each item takes its own glyph in the marker column, in ink 3.

<List marker="icon">
  <List.Item icon={<Check weight="bold" />}>Unlimited projects</List.Item>
  <List.Item icon={<Check weight="bold" />}>Priority support</List.Item>
  <List.Item icon={<Check weight="bold" />}>Advanced analytics</List.Item>
</List>

Rows

Interactive 32px rows: a leading glyph, the label, trailing meta, the current row marked.

import { House, Gear, CreditCard } from "@phosphor-icons/react";

<List marker="none" gap="none" aria-label="Pages">
  <List.Row icon={<House />} meta="/" selected>
    Home
  </List.Row>

Link Rows

Navigation rows render links through `render`.

<List marker="none" gap="none" aria-label="Docs">
  <List.Row render={<a href="/docs/start" />} aria-current="page" selected>
    Getting started
  </List.Row>
  <List.Row render={<a href="/docs/theming" />}>Theming</List.Row>
</List>

No Style

No markers: a plain stack of items.

<List marker="none">
  <List.Item>Dashboard</List.Item>
  <List.Item>Settings</List.Item>
  <List.Item>Profile</List.Item>
</List>

API reference

Component props
Prop	Type	Default	Description
`as`	`"ol" \| "ul" \| undefinedolul`	`ul`	List element. An ol numbers its items; a ul draws a bullet.
`children`Required	`React.ReactNode`	Not set	List.Item or List.Row components
`gap`	`ListGap \| undefinedxssmnone`	`sm`	Space between items: 0, 4 or 8
`Item.children`Required	`React.ReactNode`	Not set	—
`Item.icon`	`React.ReactNode`	Not set	Leading glyph, drawn in the marker column in place of the marker.
`marker`	`ListMarker \| undefinednoneicondisc`	Not set	Marker before each item, when it is not the default for `as`
`Row.children`Required	`React.ReactNode`	Not set	The row's label. Truncates to one line.
`Row.icon`	`React.ReactNode`	Not set	Leading glyph: ink 3 at rest, ink 1 on the selected row.
`Row.meta`	`React.ReactNode`	Not set	Trailing detail (a count, a path, a time), in ink 3 at the label size.
`Row.render`	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Not set	Replace the button with another element, such as a link. Accepts an element or a function that returns one.
`Row.selected`	`boolean \| undefined`	Not set	The row you are on: the neutral current fill and ink 1. Sets `aria-current` unless you pass `aria-current` or `aria-pressed` yourself; a row with `aria-pressed` is a toggled choice and takes the selection wash and ring.
`style`	`CSSProperties \| undefined`	Not set	—

Accessibility

Real ul/ol markup means screen readers announce the item count
Icons are decorative — the text has to carry the meaning
A selected row carries aria-current (or your own aria-current/aria-pressed), never colour alone
List.Row renders a button; pass render={<a href />} for navigation

IconchildUse Icon as List.Item or List.Row icon
StackalternativeUse Stack for non-semantic vertical lists and larger rhythm
SidebaralternativeUse Sidebar.Item for the app's own navigation

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.