List Box

A listbox displays a list of options and allows a user to select one or more of them.

Alpha

Beta

Gamma

<ListBox aria-label="Options">
  <ListBoxItem id="alpha">Alpha</ListBoxItem>
  <ListBoxItem id="beta">Beta</ListBoxItem>
  <ListBoxItem id="gamma">Gamma</ListBoxItem>
</ListBox>

Installation

npm

pnpm

yarn

bun

npx shadcn@latest add @dotui/list-box

Usage

Use list boxes to display a list of options and allow users to select one or more of them.

import { ListBox, ListBoxItem } from '@/components/ui/list-box'

<ListBox aria-label="Options" selectionMode="single">
  <ListBoxItem>Option 1</ListBoxItem>
  <ListBoxItem>Option 2</ListBoxItem>
  <ListBoxItem>Option 3</ListBoxItem>
</ListBox>

Anatomy

import {
  ListBox,
  ListBoxItem,
  ListBoxItemLabel,
  ListBoxItemDescription,
  ListBoxSection,
  ListBoxSectionHeader,
} from '@/components/ui/list-box'

<ListBox>
  <ListBoxSection>
    <ListBoxSectionHeader />
    <ListBoxItem>
      <ListBoxItemLabel />
      <ListBoxItemDescription />
    </ListBoxItem>
  </ListBoxSection>
</ListBox>

ListBox is the container. Each ListBoxItem is an option; give it a ListBoxItemLabel and optional ListBoxItemDescription when it holds more than a string. Group options under a ListBoxSection with a ListBoxSectionHeader.

Content

Pass items statically as children, or dynamically via items plus a render function. Each item needs a stable id.

<ListBox aria-label="Animals" items={animals}>
  {(item) => <ListBoxItem id={item.id}>{item.name}</ListBoxItem>}
</ListBox>

Selection

selectionMode sets whether options are selectable and how many. Control the selection with selectedKeys and onSelectionChange, or use defaultSelectedKeys for uncontrolled state. Pass onAction to make rows pressable without selecting them.

<ListBox
  aria-label="Options"
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={setSelected}
>
  <ListBoxItem id="a">Option A</ListBoxItem>
  <ListBoxItem id="b">Option B</ListBoxItem>
</ListBox>

Disabled items

Disable individual options by passing their keys to disabledKeys — the rest of the list stays interactive.

<ListBox aria-label="Options" disabledKeys={['b']}>
  <ListBoxItem id="a">Option A</ListBoxItem>
  <ListBoxItem id="b">Option B</ListBoxItem>
</ListBox>

Async loading

Load items on scroll with isLoading and onLoadMore, typically driven by useAsyncList, and render an empty state via renderEmptyState. See the Async Loading example.

Links

Give a ListBoxItem an href to render it as a link. With a client router configured, links use client-side navigation.

<ListBox aria-label="Links">
  <ListBoxItem href="/home">Home</ListBoxItem>
  <ListBoxItem href="/settings">Settings</ListBoxItem>
</ListBox>

Examples

Basic

Next.js

Remix

Astro

Gatsby

Edit

Copy link

Add to favorites

Junior Garcia

jrgarcia@example.com

Profile

Settings

Log out

Organized Sections

Sauces

Signature sauce

BBQ sauce

Honey mustard

Cheese

Pepperjack

Mozzarella

Blue cheese

Extras

Bacon

Sauteed onions

Async Loading

API Reference

ListBox

A listbox displays a list of options and allows a user to select one or more of them.

Prop	Type	Default
	`boolean`	`—`
	`DragAndDropHooks<NoInfer<T>>`	`—`
	`"grid" \| "stack"`	`'stack'`
	`Orientation`	`'vertical'`

	`ReactNode \| function`	`—`
	`Iterable<T>`	`—`
	`function`	`—`
	`readonly any[]`	`—`

	`SelectionMode`	`—`
	`SelectionBehavior`	`'toggle'`
	`Iterable<Key> \| "all"`	`—`
	`Iterable<Key> \| "all"`	`—`
	`function`	`—`
	`Iterable<Key>`	`—`
	`boolean`	`—`
	`boolean`	`—`
	`boolean`	`—`
	`boolean`	`—`
	`"clearSelection" \| "none"`	`'clearSelection'`

ListBoxItem

A ListBoxItem represents an individual option in a ListBox.

Prop	Type	Default
	`"danger" \| "default"`	`'default'`
	`ReactNode \| function`	`—`
	`Key`	`—`
	`boolean`	`—`
	`string`	`—`
	`T`	`—`

ListBoxSection

A ListBoxSection represents a section within a ListBox.

Prop	Type	Default
	`Key`	`—`
	`T`	`—`

	`union`	`—`
	`Iterable<T>`	`—`
	`readonly any[]`	`—`

ListBoxSectionHeader

Header rendered at the top of a ListBoxSection.

Prop	Type	Default

ListBoxLoader

Loader strip rendered below the items collection.

Supports all div attributes.

Prop	Type	Default

ListBoxVirtualizer

A Virtualizer renders a scrollable collection of data using customizable layouts. It supports very large collections by only rendering visible items to the DOM.

Prop	Type	Default
	`ReactNode`	`—`
	`T`	`—`

Last updated on 7/7/2026