ComponentsCore

List Box

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

Example

Features

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.

  • Item selection – Single or multiple selection, disabled rows, and both toggle and replace selection behaviors.
  • Keyboard navigation – List items can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
  • Layout options – Items can be arranged in a vertical or horizontal stack, or as a two-dimensional grid.
  • Drag and drop – ListBox supports drag and drop to reorder, insert, or update items via mouse, touch, keyboard, and screen reader interactions.
  • Virtualized scrolling – Use Virtualizer to improve performance of large lists by rendering only the visible items.
  • Touch friendly – Selection behavior adapts depending on the device. For example, selection occurs on mouse down but on touch up, which is consistent with native conventions.
  • Accessible – Follows the ARIA listbox pattern, with support for items and sections, and slots for label and description elements within each item for improved screen reader announcement.
  • Styleable – Items include builtin states for styling, such as hover, press, focus, selected, and disabled.

Installation

Install following dependencies:

npm install react-aria-components tw-animate-css tailwindcss-react-aria-components class-variance-authority lucide-react clsx tailwind-merge motion

Add cn helper using clsx and twMerge for conditional class merging in Tailwind components.

lib/utils.ts

Copy and paste the following code into your project.

components/ui/core/list-box.tsx
npx @libravelui@latest add list-box

Anatomy

import { ListBox, ListBoxItem } from "@/components/ui/core/list-box";
<ListBox className="max-w-2xs" items={items} selectionMode="single">
  {(item) => <ListBoxItem id={item.id}>{item.label}</ListBoxItem>}
</ListBox>

Another Examples

Multiple

Allows users to choose more than one option from a list, making it easy to manage selections that require flexibility or comparison between items.

Drag and Drop

Enables users to rearrange list items by simply dragging them, providing a smooth and intuitive way to customize the order and organization.

Edit on GitHub

Grid List

A grid list displays a list of interactive items, with support for keyboard navigation, single or multiple selection, and row actions.

Table

A table displays data in rows and columns and enables a user to navigate its contents via directional navigation keys, and optionally supports row selection and sorting.