List

A scrollable list of clickable rows: the action / navigation counterpart to SelectableList. Compose List.Item rows directly inside a List.Root; each is a <button> (with onClick) or your own element via asChild (e.g. an <a>), with an optional current highlight. It shares SelectableList's look (styled like the MultiSelect popover, with rows that highlight on hover / selection as an inset, rounded pill inside a bordered bg-popover container) and suits an account switcher or an SSO provider picker. It renders every row by default; for long lists, swap Root → VirtualRoot to window them.

1import { List } from "@ngrok/mantle/list";2import { useState } from "react";3 4function Example() {⋯5	const [activeId, setActiveId] = useState("account-2");6 7	return (8		<List.Root aria-label="Your accounts" className="max-h-80">⋯9			{accounts.map((account) => (10				<List.Item⋯11					key={account.id}12					current={account.id === activeId}13					onClick={() => setActiveId(account.id)}14				>15					<List.ItemTitle>{account.name}</List.ItemTitle>16					<List.ItemDescription>⋯17						{account.plan} · {account.memberCount} members18					</List.ItemDescription>19				</List.Item>20			))}21		</List.Root>22	);23}

A minimal version (three rows, no current state):

1import { List } from "@ngrok/mantle/list";2 3const accounts = [⋯4	{ id: "personal", name: "Cody Price", plan: "All Subscription" },5	{ id: "corp", name: "corp@ngrok.com", plan: "Enterprise Subscription" },6	{ id: "dogfood", name: "dogfood@ngrok.com", plan: "Free" },7];8 9<List.Root aria-label="Switch account" className="max-h-80">⋯10	{accounts.map((account) => (11		<List.Item key={account.id} onClick={() => {}}>⋯12			<List.ItemTitle>{account.name}</List.ItemTitle>13			<List.ItemDescription>{account.plan}</List.ItemDescription>14		</List.Item>15	))}16</List.Root>;

The same three rows hand-built without List, with the same chrome and no virtualization (fine for short, static lists):

1import { cx } from "@ngrok/mantle/cx";2 3const accounts = [⋯4	{ id: "personal", name: "Cody Price", plan: "All Subscription" },5	{ id: "corp", name: "corp@ngrok.com", plan: "Enterprise Subscription" },6	{ id: "dogfood", name: "dogfood@ngrok.com", plan: "Free" },7];8 9<ul className="border-popover bg-popover scrollbar m-0 max-h-80 list-none overflow-y-auto overflow-x-hidden rounded-md border px-0 py-1">⋯10	{accounts.map((account) => (11		<li key={account.id} className="px-1 pb-px last:pb-0">⋯12			<button⋯13				type="button"14				onClick={() => {}}15				className={cx(16					"flex w-full cursor-pointer flex-col gap-0.5 rounded-md bg-transparent px-2 py-1.5 text-left text-sm",17					"hover:bg-active-menu-item",18					"focus-visible:bg-active-menu-item focus-visible:outline-hidden",19				)}20			>21				<span className="text-strong font-medium">{account.name}</span>22				<span className="text-body leading-4">{account.plan}</span>23			</button>24		</li>25	))}26</ul>;

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.

1import { List } from "@ngrok/mantle/list";2import { useState } from "react";3 4// `VirtualRoot` is a drop-in for `Root` — same `Item` children, same props.5function Example() {⋯6	const [activeId, setActiveId] = useState("account-2");7 8	return (9		<List.VirtualRoot aria-label="Your accounts" className="max-h-80">⋯10			{accounts.map((account) => (11				<List.Item⋯12					key={account.id}13					current={account.id === activeId}14					onClick={() => setActiveId(account.id)}15				>16					<List.ItemTitle>{account.name}</List.ItemTitle>17					<List.ItemDescription>⋯18						{account.plan} · {account.memberCount} members19					</List.ItemDescription>20				</List.Item>21			))}22		</List.VirtualRoot>23	);24}

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).

1import { cx } from "@ngrok/mantle/cx";2import { MediaObject } from "@ngrok/mantle/media-object";3import { List } from "@ngrok/mantle/list";4 5<List.Root aria-label="Identity providers" className="max-h-72">⋯6	{providers.map((provider) => (7		<List.Item key={provider.id} asChild className="py-2.5">⋯8			<a href={`#${provider.id}`}>⋯9				<MediaObject.Root className="items-center gap-3">⋯10					<MediaObject.Media>⋯11						<provider.Icon weight="duotone" className={cx("size-8", provider.tint)} />12					</MediaObject.Media>13					<MediaObject.Content className="flex flex-col gap-0.5">⋯14						<List.ItemTitle>{provider.name}</List.ItemTitle>15						<List.ItemDescription>{provider.owner}</List.ItemDescription>16					</MediaObject.Content>17				</MediaObject.Root>18			</a>19		</List.Item>20	))}21</List.Root>;

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:

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

List.VirtualRoot

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

List.Item

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

List.ItemTitle / List.ItemDescription

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