Skip to main content

List

A scrollable, optionally-virtualized list of clickable items. Compose List.Item rows inside a List.Root, and give each row an onClick.

When to use

  • Show a scrollable list of items that each run an action or navigate, such as an account switcher or an SSO provider picker.
  • Show a long list: swap Root for VirtualRoot to window the rows. Root renders every row.
  • Prefer SelectableList when the user selects rows with checkboxes. List is its action and navigation counterpart.
  • Prefer DropdownMenu when the actions open in a menu from a button.

Current row

Set current on one List.Item to highlight it, such as the active account in an account switcher.

Composition

List.Root   (or .VirtualRoot)└── List.Item    ├── List.ItemTitle    └── List.ItemDescription
  • Root renders the rounded, scrollable bg-popover container and its Item children (all of them, non-virtualized). Reads each item's current / disabled to style its row. Bound its height (max-h-*, h-*, or min-h-0 flex-1 in a flex parent) so long lists scroll.
  • VirtualRoot is the drop-in windowed variant: same Item children, only the visible slice mounted. See Virtualization.
  • Item is a clickable row: a <button> by default (onClick), or your own element via asChild. current gives the tinted pill.
  • ItemTitle / ItemDescription are optional styled spans for the emphasized title and de-emphasized sub-line.

Virtualization

List.Root renders every row: simplest, and right for the short lists most action/navigation menus are. For a long list (hundreds+ of rows), swap in List.VirtualRoot: it windows the same Item children via @tanstack/react-virtual, mounting only what's visible. The call site is otherwise identical: same children, same props. (@tanstack/react-virtual ships with every list entrypoint; it is small, a few kB gzipped, and does no windowing work until a VirtualRoot renders.)

On the server, VirtualRoot renders the first slice of rows, sized by estimateItemHeight and overscan. The rest mount after hydration measures the viewport. Root renders every row in the server HTML. If the whole list must be in that HTML (for find-in-page, or for a reader without JavaScript), pick Root.

Windowing trade-off. Off-screen rows aren't in the DOM, so Tab and browser find-in-page only reach mounted rows (arrow keys still span the full list; they mount the target row before focusing it). That is the right trade for a large enough list. Prefer Root until a list is actually long.

Polymorphism

Render rows as links by passing asChild and an <a>: the row chrome (hover pill, keyboard-focus tint) applies to your element, so clicking navigates. Rows compose freely: each one here is a MediaObject with the provider icon on the left and the name over a de-emphasized owner on the right (an SSO identity-provider picker, as a list rather than a stack of cards).

Appearance

List shares the look of SelectableList, which is styled like the MultiSelect popover. Rows highlight on hover and on selection as an inset, rounded pill inside a bordered bg-popover container.

Accessibility

The list is a role="list" of role="listitem" rows (the tag is a <div>; per WAI-ARIA the role, not the tag, carries the semantics); each Item is a focusable <button> (or your asChild element) inside its row. It is a non-selecting list, not a selection widget; that's SelectableList's job. Set an aria-label (or aria-labelledby) on the Root so the list has an accessible name. The current row is announced via aria-current, not just tinted. Disabled rows are dimmed: a <button> row sets the native disabled, while an asChild row is conveyed with aria-disabled, removed from the tab order, and swallows clicks. For a genuinely disabled link, prefer omitting or removing the href.

Keyboard: rows keep their native tab order, and Arrow↑/Arrow↓ / Home / End also move focus between rows, skipping disabled ones (no wrap; arrowing past the last row holds). The focused row lights up with the same tint as hover instead of drawing a focus ring on the item, matching the SelectableList active row. Arrow navigation works under VirtualRoot too (a jump scrolls the target row into view and mounts it before moving focus), though off-screen rows still aren't reachable by Tab alone (see Virtualization).

API Reference

List.Root

The non-virtualized container. Accepts all <div> props, plus:

PropTypeDefaultDescription
childrenReactNodeList.Item rows (all are rendered).

Bound the height (e.g. className="max-h-80") so long lists scroll.

List.VirtualRoot

The windowed container, with the same surface as Root (compose the same Item children), plus the virtualizer knobs:

PropTypeDefaultDescription
childrenReactNodeList.Item rows (only the visible window is mounted).
estimateItemHeight?number44Estimated item height (px) used to seed the virtualizer before measure. With overscan, it also sizes the server-rendered first slice.
overscan?number8Rows rendered beyond the visible window on each side.

List.Item

A clickable row. Accepts all <button> props (minus type), plus:

PropTypeDefaultDescription
current?booleanfalseMarks the row as the current one (tinted pill) and sets aria-current, so the state is announced, not just shown. Omit for a plain action/navigation list.
disabled?booleanfalseDisables the row (dimmed). disabled on the button; with asChild, aria-disabled + removal from the tab order, and clicks are swallowed. Prefer omitting href for a disabled link.
asChild?booleanfalseRender the row as the child element you pass (e.g. an <a>) instead of a <button>.

List.ItemTitle / List.ItemDescription

Styled <span>s for the title and de-emphasized sub-line inside an Item. Both accept all <span> props.