An unframed container for displaying related items vertically. Lists provide one consistent visual treatment, multiple item types, and optional keyboard navigation.
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| ariaLabel | string | Yes | - | Accessible label for the list |
| navigation | boolean | No | true | Enable arrow key navigation |
| autofocus | boolean | No | false | Focus the first item on mount |
| gap | Gap | No | "small" | Vertical space between items |
| Prop | Type | Default | Description |
|---|---|---|---|
| headline | string | Required | Primary text |
| body | string | - | Optional supporting text |
| icon | IconType | - | Context-colored icon inside the primary content |
| iconPosition | Position | "start" | Position of the icon |
| iconSize | Size | "medium" | Size of the icon |
| addOn | ReactNode | - | Trailing status or action outside the primary content |
All item components accept text props such as headline and body, plus an optional icon. Icons are part of the primary item content and inherit its semantic color. addOn provides a trailing status or action slot outside interactive buttons. Static and interactive items share the same padding, typography, icon spacing, and truncation defaults so mixed lists remain aligned.
Lists have no surrounding background or border. Interactive items receive a rounded hover treatment, keeping the list lightweight in cards, sidebars, popovers, and full-width layouts.
<List ariaLabel="Settings">
<ListItem
headline="Notifications"
body="Manage your notification preferences"
icon="bell"
/>
<ListButtonItem
color="secondary"
headline="Account"
body="Update your profile information"
icon="user"
onClick={() => {}}
/>
<ListLinkItem
href="/help"
color="secondary"
headline="Help Center"
icon="circle-question-mark"
/>
</List>
ListButtonItem and ListLinkItem support semantic text colors:
<ListButtonItem
color="primary"
headline="Create"
icon="plus"
onClick={() => {}}
/>
<ListButtonItem
color="secondary"
headline="Edit"
icon="pencil"
onClick={() => {}}
/>
<ListButtonItem
color="negative"
headline="Delete"
icon="trash-2"
onClick={() => {}}
/>
Custom add-on content can use color="inherit" to follow the item’s disabled, selected, or semantic foreground color.
<ListButtonItem
headline="Miner"
body="Ready to join the crew"
icon="hard-hat"
addOn={
<Row gap="xsmall" align="center">
<Span color="inherit">120</Span>
<Icon color="inherit" icon="coins" size="small" />
</Row>
}
onClick={() => {}}
/>
Interactive items support a selected prop. Link items also expose the state through aria-current="page".
<ListLinkItem
href="/analytics"
headline="Analytics"
selected={currentPage === "analytics"}
/>
<List ariaLabel="Selection colors">
<ListButtonItem
headline="Unselected item"
body="This body uses the default item color"
onClick={() => {}}
/>
<ListButtonItem
headline="Selected item"
body="This body uses the selected highlight color"
selected
onClick={() => {}}
/>
</List>
Group related items with collapsible sections:
<List ariaLabel="Documentation">
<Sublist label="Getting Started">
<ListItem headline="Installation" />
<ListItem headline="Quick Start" />
</Sublist>
<Sublist label="Components">
<ListItem headline="Button" />
<ListItem headline="Input" />
</Sublist>
</List>
Lists use arrow key navigation by default, following the WAI-ARIA grid pattern:
Disable list-managed navigation when the contents manage focus themselves:
<List ariaLabel="Form fields" navigation={false}>
...
</List>