List

Related components

npx garn-ui add list

Registry

list

Source

list.tsx

Deps

@radix-ui/react-slotlucide-react

Registry deps

utilsuse-controllable-stateuse-controllable-key-setuse-merged-refsortablecheckboxspinner

Overview

Guidelines

Best practices

Content guidelines

• Lead the row with the title (what it is); keep the description terse and let it truncate.
• Keep trailing metadata short (a time, a badge, a count); move anything actionable into List.Actions.

Accessibility

Role

list

Focus

Inert/navigational rows aren't focusable — only the title link and List.Actions are. The keyboard grid puts a roving tabindex on the rows (active row = 0, others = -1) and roves the active row's in-row controls; the radiogroup roves its radios. Every focusable control keeps a 2px --garn-ring focus ring.

• • Presentational / navigational lists are a real <ul role=list> of <li role=listitem>; a navigational row uses the 'card-with-primary-action' overlay — List.Title becomes the sole <a>/<button> with an ::after spanning the row (one tab stop) while List.Actions sit above the overlay with their own tab stops (no nested interactives).
• • `selectionMode="multiple"` (and `keyboardNavigation`) is a real ARIA grid: a <div role=grid aria-multiselectable> of <div role=row aria-selected> rows, each wrapping a <div role=gridcell>. A grid CANNOT be built from <ul>/<li> because ARIA forbids role=row on <li>, so grid mode forks the element types.
• • The grid roves row focus with a roving tabindex (one row tabbable at a time): Arrow Up/Down, Home/End, PageUp/PageDown move focus; type-ahead jumps to a title; Space toggles the focused row; Shift+Arrow / Shift+Click extend a range; ⌘/Ctrl+A selects all; Escape clears; Enter activates a navigational row. In-row controls (checkbox, link, actions) rove with the active row so Tab steps through the active row only.
• • `selectionMode="single"` flips the <ul> to role=radiogroup, the <li> wrappers take role=presentation, and each row renders a roving role=radio (Arrow keys move + select). It is a single-choice form control, not a grid.
• • The bulk-action bar (List.SelectionBar) has a tri-state select-all Checkbox and announces the selected count via a polite live region; disabled keys are skipped by select-all and range.
• • An expandable row's disclosure is a real <button aria-expanded aria-controls>; the revealed List.ItemDetail is wired by aria-controls (no role=region — an unnamed region is an anti-pattern).
• • Per-row status: loading/saving set aria-busy and show a Spinner; the row tone is a decorative accent (error implies the danger tone) — never the sole signal. Give the list an accessible name via `label`, `aria-label`, or `aria-labelledby` (dev-warns if missing).