List

Pro

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#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add list

Usage#

This example is part of Koala UI Pro

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.

  • Notifications
    Push, email and in-app
  • Starred
    Pinned to the top of every view
  • Archive
    Hidden from the inbox
Playground
Props

A bordered surface, or rows flush on the page.

A hairline rule between rows.

Per row. Hover, press and focus affordance.

Parts

Leading icon, Avatar or thumbnail.

A second line under the title.

Trailing badge, timestamp or chevron.

This example is part of Koala UI Pro

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.

  • Notifications
    3
  • Language
    English
  • Notifications
    3
  • Language
    English
  • Payment received
    2m
  • New sign-in from Lisbon
    14m

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.

Units

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 notifications
    Alerts on this device
  • Private profile
    Hide from search
  • Beta features
    Early 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.

Nothing here yet

New items will show up here.

No results

Try a different search or clear the filters.

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.

PropTypeDefaultDescription
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.
dividedbooleantrueA hairline rule between rows.
bleedbooleantrueplain 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.
navigablebooleanfalseRoving 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.
asChildbooleanfalseRenders the child (an <ol>, say) as the root via Radix Slot.

ListItem

One row. Renders an <li> and forwards all its props.

PropTypeDefaultDescription
asChildbooleanfalseHands the row surface to a single <a> or <button> child while the <li> keeps the divider. Implies interactive.
interactiveboolean-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.
currentboolean | "page" | "step" | "location" | "date" | "time"-The row the screen is showing: a full fill, an ink bar, and aria-current on the row surface.
selectedboolean-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.
unreadboolean-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.
actionsReactNode-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.

PropTypeDefaultDescription
lines1 | 2 | 3 | "none"1Lines 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.

PropTypeDefaultDescription
lines1 | 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.

PropTypeDefaultDescription
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.
stackedbooleanfalseTwo 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.

PropTypeDefaultDescription
checkedboolean-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.

PropTypeDefaultDescription
countnumber-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.

PropTypeDefaultDescription
media"avatar" | "none""avatar"Reserve the 32px leading mark.
lines1 | 2 | 32Title plus description lines.
metabooleantrueReserve 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.

PropTypeDefaultDescription
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).
titleReactNode-Overrides the title.
descriptionReactNode-Overrides the description.
actionReactNode-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.

PropTypeDefaultDescription
aria-labelstring-Required: the control has no visible text.

FAQ#

Reach for List when you have rows of content with leading media, a title, and a description, like a settings or member list. Data Table is for columnar tabular data, and Description List is for key/value detail pairs.