Yugen UI

List

List shows a vertical sequence of related items, keyboard navigable, with single or multiple selection.

Each ListItem has media (Avatar / icon), a title, a description and an actions area. selectionMode turns on selection (multiselect shows a Checkbox); navigationMode="composite" lets → / ← move into and out of the buttons inside an item.
  • Alex ChenSoftware engineer
  • Maria GarciaDesigner
  • Sam LeeProduct manager
  • Jordan KimQA engineer
1 selected · use ↑ ↓ and Space to select

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX
// npm install yugen-uiimport { List, ListItem } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

  • Q3 report.docxEdited 2 hours ago
  • Cover image.pngEdited yesterday
  • Contract.pdfEdited 3 days ago

Basic

A static List with an icon, title and description.

  • Today
  • Last 7 days
  • Last 30 days

Single selection

selectionMode="single": the selected item gets a brand tint and a checkmark.

  • Maria GarciaHere's the new homepage design. Could you take a look?
  • Sam LeeSprint planning moved to Thursday at 10:00 AM.

Outline & actions

appearance="outline" turns each item into a card; composite: → moves into the buttons, ← / Esc goes back to the item.

Usage

Do
  • Give the List an aria-label, and each ListItem a stable value when selection is on.
  • Use composite when items contain their own buttons or menus.
  • Give each item one clear main action.
Don't
  • Don't nest a List in a ListItem. Use Tree for hierarchical data.
  • Don't mark selected items with color alone; the checkbox / checkmark already covers this.
  • Don't use List for data with several columns. Use Table.

Props

Prop · TypeDefaultDescription
selectionMode"none" | "single" | "multiselect"Default: "none"Selection mode; multiselect shows a Checkbox.
selectedItems / defaultSelectedItemsstring[]Default: —Values of the selected items (controlled / uncontrolled).
onSelectionChange(selectedItems: string[]) => voidDefault: —Called when an item is selected or deselected.
navigationMode"items" | "composite"Default: items when selection is onArrow key navigation (roving tabindex).
appearance"default" | "outline"Default: "default"outline: each item is a bordered card with rounded-xlarge corners. The old name variant is deprecated (removed in 1.0).
ListItem.media / title / description / actionsReactNodeDefault: —Content areas of the item.
ListItem.onAction(event) => voidDefault: —Main action on click / Enter.
ListItem.value / disabledstring / booleanDefault: —Identifier and disabled state.