ListBox

A listbox can be built using the <select> and <option> HTML elements, but this is not possible to style consistently cross browser. ListBox helps you build accessible listbox components that can be styled as needed.

Note: ListBox only handles the list itself. For a dropdown, see Select.

Installation

npx shadcn@latest add https://backchanel.com/default/list-box

Usage

import { Item, ListBox } from "@/components/ui/list-box"

<ListBox aria-label="Example list box">
  <Item>Option 1</Item>
  <Item>Option 2</Item>
  <Item>Option 3</Item>
</ListBox>

Examples

Basic

Dynamic Content

Selection

When selectionBehavior is set to "replace", clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.

Links

By default, link items in a ListBox are not selectable, and only perform navigation when the user interacts with them. However, with the "replace" selection behavior, items will be selected when single clicking or pressing the Space key, and navigate to the link when double clicking or pressing the Enter key.

Client Side Routing

The <ListBoxItem> component works with frameworks and client side routers like Next.js, Remix and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Sections

Static

Dynamic

Text Slots

Disabled Items

In dynamic collections, it may be more convenient to use the disabledKeys prop at the ListBox level instead of isDisabled on individual items. Each key in this list corresponds with the id prop passed to the ListBoxItem component, or automatically derived from the values passed to the items prop (see the Collections for more details). An item is considered disabled if its id exists in disabledKeys or if it has isDisabled.

Empty State

Drag and Drop

Drag Between Lists