List for React

Rows sit in groups, one group per status, and move up and down between them by drag or by keyboard.

Use it for a priority list or tasks by status in a narrow panel, where columns side by side wouldn't fit. Stages people scan across belong on a Kanban board, and rows you sort by a column belong in a Table. In React, the list writes its own pointer and key handling, so there is no drag-and-drop package to install, and Base UI isn't involved in the move.

Installation

Anatomy

ListProvider
└── ListGroup
    ├── ListHeader
    └── ListItems
        └── ListItem

Usage

import {
  ListGroup, ListHeader, ListItem, ListItems, ListProvider,
} from "@/components/ui/list";

const statuses = [
  { color: "var(--muted-foreground)", id: "todo", name: "To Do" },
  { color: "var(--primary)", id: "done", name: "Done" },
];

const [tasks, setTasks] = useState([
  { id: "1", name: "Research competitors", status: "todo" },
  { id: "2", name: "Set up the project", status: "done" },
]);

<ListProvider onValueChange={setTasks} value={tasks}>
  {statuses.map((status) => (
    <ListGroup id={status.id} key={status.id}>
      <ListHeader color={status.color} name={status.name} />
      <ListItems>
        {tasks
          .filter((task) => task.status === status.id)
          .map((task) => (
            <ListItem id={task.id} key={task.id} name={task.name} />
          ))}
      </ListItems>
    </ListGroup>
  ))}
</ListProvider>

The items are one flat array: each has an id, a name and the status of the group it sits in, and their order in the array is their order in each group. A move hands the whole array back through onValueChange, so the list is always controlled.

Accessibility

Each row is focusable and says how to move it. A polite live region announces every pick-up, step, drop and cancel with the row's name, its group (the header's text) and its position.

Demos

Custom Items

A support queue grouped by priority, each row with a grip icon, its title, a Badge and the owner's avatar, and a count in each header. ListItem takes any children in place of its name, and ListHeader takes children in place of its dot and name. The whole row is still the handle, so the grip is only a hint; links, buttons and fields inside a row keep their own clicks.

Move Events

The line under the list shows what onMoveStart and onMoveEnd report: the row's id, where it came from, and where it went to, which is null when the move was cancelled. Both fire for the pointer and the keyboard. Use them to save a move to your server, and keep onValueChange for the array itself.

Scrolling

Ten roadmap items in a list with h-80 and overflow-y-auto on ListProvider, so the list scrolls inside its own frame. Drag a row toward the top or bottom edge and the list scrolls under it; a list without a height scrolls the page instead. Give the list a height when it shares a panel with other content.

FAQ

API Reference