List
The canonical vertical list group: stacked rows with leading media, a title and description, and trailing meta or actions. Rows are inert by default and become links or buttons via asChild.
Installation#
Usage#
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import {
List,
ListItem,
ListItemMedia,
ListItemContent,
ListItemTitle,
ListItemDescription,
ListItemMeta,
ListItemIndicator,
ListItemAction,
} from "@/components/ui/list"
<List>
<ListItem actions={<ListItemAction aria-label="…" />}>
<ListItemMedia />
<ListItemContent>
<ListItemTitle />
<ListItemDescription />
</ListItemContent>
<ListItemMeta>
<ListItemIndicator />
</ListItemMeta>
</ListItem>
</List>Playground#
Both shapes at once. Props belong to the list, except interactive, which is set per row on ListItem; Parts are the row slots you compose in or leave out.
- NotificationsPush, email and in-app
- StarredPinned to the top of every view
- ArchiveHidden from the inbox
A bordered surface, or rows flush on the page.
A hairline rule between rows.
Per row. Hover, press and focus affordance.
Leading icon, Avatar or thumbnail.
A second line under the title.
Trailing badge, timestamp or chevron.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Variants#
card (default) bands the rows inside a bordered surface; plain drops the chrome so rows sit flush on whatever holds them. Both keep the divider rule. filled gives the block a fill of its own, for rows that already sit on a surface: a feed of items inside a card or a side panel, where a ring alone blends into the ground.
- Notifications3
- LanguageEnglish
- Notifications3
- LanguageEnglish
- Payment received2m
- New sign-in from Lisbon14m
Interactive rows#
Pass asChild with an <a> or <button> to make the whole row a link/button: valid <li><a> nesting, with a hover fill that deepens on press, and an inset focus ring. It implies interactive; set interactive on its own for a row that handles onClick without being a link.
Bleed#
One rule either way: a row's fill sits 8px outside its text and never touches the container's edge. bleed only decides who owns those 8px. With the default, the list sits in a column that already has a margin (a page, a docs column, a padded Card): the row hangs 8px into it, so its text lines up with the heading above. When the list is a container's edge-to-edge content (an app pane, a popover, a Card with no padding), pass bleed= and p-2 on the List: the list pads 8px, the row pads 8px, and the text starts 16px in, under the header title. Selectable rows without rules sit 2px apart either way, 4px with currentStyle="lift" so a raised row's shadow clears the next one.
With controls#
Rows compose any Koala part in the meta slot. Here each row stays inert (it isn't a link) and drops a Switch on the right. The classic settings list.
- Push notificationsAlerts on this device
- Private profileHide from search
- Beta featuresEarly access builds
Current row#
In a list-detail screen one row is the record the rest of the screen is showing: the open thread, the chapter being read. Mark it with current on ListItem. It answers on two channels a hover never touches, so the two can't be confused in any theme: the fill goes to full strength and stays there under the pointer, and an ink bar sits on the row's leading edge, the same mark the Sidebar's active row carries. It also sets aria-current on the row surface (the <button> or <a> under asChild); pass current="page" when the rows are navigation links. When the selection moves with the keyboard, see Keyboard selection.
Selection styles#
Selection is ink, never brand, and one signal, never two. Three styles cover the selectable lists of an app; each pairs a hover that is a lighter step of its own current, so a hovered row never reads heavier than the open one. chip is a faint ink fill. lift picks the row up as a tile, raised by elevation, with rows 4px apart. edge is the classic list: square rows, hairlines from edge to edge and a 3px ink bar flush to the list's edge; pair it with divided.
currentStyle="chip"currentStyle="lift"currentStyle="edge"Inbox rows#
A row in a mail, chat or ticket list carries a read state, a time and a few actions. unread keeps the title medium and announces it; a read row drops to regular, so the difference is weight, not colour. ListItemIndicator is the brand dot, and a stacked meta at a fixed width puts it under the time, so every title truncates at the same edge. actions render beside the row, never inside its button, rest collapsed and take the time's place on hover or focus. Hover a row, or tab to it.
Keyboard selection#
People who live in a list drive it from the keyboard. Pass navigable and the list becomes one tab stop: the arrow keys, Home, End and Page Up/Down move focus from row to row, Enter opens the focused one, and Tab leaves the list. The focus ring marks where you are, the current style marks what is open, so the two never compete and the selection stays ink. When the focused row disappears (archived, say), focus lands on the row that took its place instead of falling to the page.
Tab into the queue, then ↑ ↓ Home End to move, Enter to open
Multi-select#
For bulk work, selectionMode="multiple" turns the list into a listbox and useListSelection keeps the state. A click still opens a row; Shift-click selects a range, Cmd or Ctrl-click and Space toggle one. ListItemCheckbox wraps the avatar, so the face shows at rest and the box steps in on hover and while anything is selected, and ListSelectionBar floats the count and the bulk actions at the foot of the pane. Select a few and archive them.
Loading#
ListItemSkeleton holds the real row's grid: the same mark, the same line boxes and the same time column, so the first load doesn't jump when the rows arrive. Set aria-busy on the List while it loads.
Empty states#
An empty list means one of three things, and each says so: empty (nothing yet), filtered (a search with no matches, offer to clear it) and error (the load failed, offer to retry, announced as an alert). The copy comes from LabelsProvider; one outline action at most.
New items will show up here.
Try a different search or clear the filters.
Check your connection and try again.
Lines#
lines sets how many lines the title and the description may take. The title defaults to 1, one line with an ellipsis, so a long name never pushes the meta off the row; the description defaults to "none" and wraps in full. Pass 1 to keep an excerpt on one line, 2 or 3 to clamp at a word, or "none" on a title that is the content itself, like a pinned note. A truncate class on a description works too: its pretty wrapping is only ever a default.
- Freeze on the billing service from Thursday 18:00 until the migration lands.Ana Torres, pinned today
- The on-call rotation moves to Mondays next month, so swap your shifts in the calendar before Friday and tell the team lead once you have.Marc Vidal, pinned yesterday, with a link to the rotation calendar and the swap form
API reference#
List
The root. Renders a <ul> and forwards all its props. Every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "card" | "filled" | "plain" | "card" | card bands the rows in a ringed surface; filled adds its own fill, for rows on a surface already; plain sits them flush on the ground. |
| divided | boolean | true | A hairline rule between rows. |
| bleed | boolean | true | plain only. Who owns the 8px between the fill and the text: true hangs the row into the column's own margin (a page, a padded Card); false keeps it in the list's box, for a list that is a container's edge-to-edge content (a pane, a popover), with p-2 on the List. |
| currentStyle | "bar" | "ring" | "chip" | "lift" | "edge" | "bar" | How the current row is marked. chip is a faint ink fill, lift raises the row as a tile (rows 4px apart), edge is the classic flush ink bar over square rows. bar suits navigation; ring is the brand cursor for game-style selection. |
| navigable | boolean | false | Roving focus: one tab stop for the list, arrow keys, Home, End and Page Up/Down move focus between rows, and focus moves to the next row when the focused one is removed. On by default for a listbox. |
| selectionMode | "none" | "single" | "multiple" | "none" | none is a list of links or buttons with aria-current. single and multiple make it a listbox: rows become options with aria-selected, and actions are dropped, since a listbox can't hold controls. |
| asChild | boolean | false | Renders the child (an <ol>, say) as the root via Radix Slot. |
ListItem
One row. Renders an <li> and forwards all its props.
| Prop | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Hands the row surface to a single <a> or <button> child while the <li> keeps the divider. Implies interactive. |
| interactive | boolean | - | Hover, press and focus affordance. Defaults to asChild. On a plain list the fill is a band as wide as the rules; with divided={false} it rounds into a pill. |
| current | boolean | "page" | "step" | "location" | "date" | "time" | - | The row the screen is showing: a full fill, an ink bar, and aria-current on the row surface. |
| selected | boolean | - | Part of a multi-selection: a soft ink fill and aria-selected in a listbox. useListSelection hands it out with the click and Space handlers. |
| unread | boolean | - | Read state, opt-in. true keeps the title medium and prefixes it for screen readers; false sets the title regular, so unread rows stand out by weight, not colour. |
| actions | ReactNode | - | Hover-revealed ListItemActions. They render beside the row, never inside it, so a row that is a button can carry buttons; they rest collapsed and take the meta's place on hover or focus. |
ListItemMedia
Leading media: a bare icon, an Avatar or a small image. Forwards native <div> props.
ListItemContent
The text column holding title and description. Forwards native <div> props.
ListItemTitle
The primary line. Forwards native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| lines | 1 | 2 | 3 | "none" | 1 | Lines before the ellipsis, so a long title never pushes the meta off the row. none wraps in full. |
ListItemDescription
The muted secondary line. Forwards native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| lines | 1 | 2 | 3 | "none" | "none" | Wraps in full by default; 1 truncates, 2 or 3 clamp. |
ListItemMeta
The trailing slot: badges, a timestamp, a chevron or a control. Hidden while the row's actions show. Forwards native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| width | "auto" | "sm" | "md" | "auto" | A fixed, right-aligned column (56px or 64px), so every title truncates at the same edge whatever the time reads. |
| stacked | boolean | false | Two lines, on the title's and the description's rows: the time on top, an indicator under it. Each child is one line. |
ListItemCheckbox
The selection box in the media slot. Wrap the row's avatar in it: the face shows at rest and the box takes its place on hover, on focus and while anything is selected. Shift-click extends the range.
| Prop | Type | Default | Description |
|---|---|---|---|
| checked | boolean | - | Whether the row is selected. |
| onCheckedChange | (checked, modifiers) => void | - | Called with the new state and the click's modifier keys. |
ListSelectionBar
A floating bar at the foot of the pane with the count, Select all, Clear and your bulk actions. It announces the count and renders nothing while the count is zero.
| Prop | Type | Default | Description |
|---|---|---|---|
| count | number | - | How many rows are selected. |
| onClear | () => void | - | Clears the selection. |
| onSelectAll | () => void | - | Shows a Select all button. |
ListItemSkeleton
A loading row on the real row's grid, so nothing jumps when the data lands.
| Prop | Type | Default | Description |
|---|---|---|---|
| media | "avatar" | "none" | "avatar" | Reserve the 32px leading mark. |
| lines | 1 | 2 | 3 | 2 | Title plus description lines. |
| meta | boolean | true | Reserve the fixed time column. |
ListEmpty
What a list shows when it has no rows, for three different reasons. Copy comes from LabelsProvider and can be overridden per use; pass one outline action at most.
| Prop | Type | Default | Description |
|---|---|---|---|
| reason | "empty" | "filtered" | "error" | "empty" | A list with nothing in it yet, a filter with no matches, or a load that failed (announced as an alert). |
| title | ReactNode | - | Overrides the title. |
| description | ReactNode | - | Overrides the description. |
| action | ReactNode | - | One action: Clear filters, Retry. |
useListSelection
Multi-select state for a list of ids: click opens, Shift-click selects a range, Cmd or Ctrl-click and Space toggle. Returns getItemProps(id, onOpen), getCheckboxProps(id), listProps, count, clear and selectAll; ids that leave the list drop out of the selection.
ListItemIndicator
The unread mark: a brand dot sized for the meta column. Decorative; the row's unread prop announces the state.
ListItemAction
One hover-revealed row control: a small ghost icon button with a 16px glyph. Pass it in the row's actions.
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | - | Required: the control has no visible text. |