List

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#

Anatomy#

import {
  List,
  ListItem,
  ListItemMedia,
  ListItemContent,
  ListItemTitle,
  ListItemDescription,
  ListItemMeta,
} from "@/components/ui/list"

<List>
  <ListItem>
    <ListItemMedia />
    <ListItemContent>
      <ListItemTitle />
      <ListItemDescription />
    </ListItemContent>
    <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.

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.

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#

On a plain list an interactive row bleeds its fill 8px past the text column (-mx-2, a row 1rem wider, 2px between pills), so the text stays on the column and the fill gets air: the menu look, and the default. Inside a Card's padding, or where each row is a card of its own, that bleed lands on the frame. Passbleed= on the List: the row stays in the list's box, keeps its 8px inner padding, adds no gap of its own, and the spacing between rows is the container's (gap-* on the List).

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.

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.

Keyboard selection#

The bar is right when the current row is one landmark in a list people point at. When the selection IS the cursor, moved by arrow keys or a game binding while focus stays on the container, a full fill and a 3px bar sit too close to a hover. PasscurrentStyle="ring" on the List: the current row takes the brand, a channel a hover never uses, as a faint brand wash and a 1px inset brand ring that follows the row's radius. Keep "bar" (the default) for pointer-driven lists and navigation; use "ring" wherever a key moves the selection.

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.

API reference#

FAQ#