Skip to content
shadcn.io
shadcn.io is not affiliated with official shadcn/ui

Shadcn Listbox for React and Tailwind

Select a single or multiple items from a list.

Brazil
Mexico
Ireland

Installation

bunx --bun shadcn@latest add https://kit.dev/r/listbox.json

Anatomy

Listbox
├── ListboxValueText
└── ListboxContent
    ├── ListboxEmpty
    └── ListboxItemGroup
        ├── ListboxItemGroupLabel
        └── ListboxItem
            ├── ListboxItemText
            ├── ListboxItemIndicator
            └── ListboxShortcut

Usage

import { createListCollection } from "@ark-ui/react/collection";
import {
  Listbox,
  ListboxContent,
  ListboxItem,
  ListboxLabel,
} from "@/components/ui/listbox";
const collection = createListCollection({
  items: [
    { label: "Brazil", value: "br" },
    { label: "Mexico", value: "mx" },
    { label: "Ireland", value: "ie" },
  ],
});

<Listbox collection={collection}>
  <ListboxContent>
    {collection.items.map((item) => (
      <ListboxItem item={item} key={item.value}>
        {item.label}
      </ListboxItem>
    ))}
  </ListboxContent>
</Listbox>

Controlled

Use value and onValueChange to control the listbox externally.

States

Disabled

Disable the entire listbox with the disabled prop.

Orientation

Use orientation prop to change the orientation of the listbox.

Horizontal

Selection Mode

Multiple

Set selectionMode="multiple" to allow selecting multiple items.

Extended

Set selectionMode="extended" to select multiple items with Cmd/Ctrl modifier.

None

Set selectionMode="none" to disable selection.

Examples

With Icon

With Description

Image Explorer

Transfer List

Grouping

Use groupBy in createListCollection and <ListboxItemGroup heading={}> with <ListboxItemGroupLabel> to group items.

With Filter

Filter items using useListCollection with useFilter from @ark-ui/react. Call filter when the search input changes to filter items by label.

With Popover

Use the listbox within a popover to create dropdown-like selection menus that overlay other content without taking up permanent screen space.

Grid Layout

Use createGridCollection with columnCount and grid CSS for a grid layout.

API Reference

Listbox

Root component. Manages selection state and keyboard navigation.

PropTypeDefault
collectionListCollection<T>required
valuestring[]-
defaultValuestring[][]
onValueChange(details: ValueChangeDetails<T>) => void-
selectionMode"single" | "multiple" | "extended""single"
orientation"vertical" | "horizontal""vertical"
disabledboolean-
deselectableboolean-
loopFocusbooleanfalse

ListboxContent

Holds the list of options.

PropTypeDefault
asChildboolean-
classNamestring-

ListboxItem

A single selectable list option.

PropTypeDefault
itemTrequired
variant"default" | "destructive""default"
asChildboolean-
highlightOnHoverboolean-

ListboxItemText

Text content for a list item.

PropTypeDefault
asChildboolean-
classNamestring-

ListboxItemIndicator

Checkmark or icon shown when the item is selected.

PropTypeDefault
childrenReactNodeCheckIcon
asChildboolean-
classNamestring-

ListboxItemGroup

Groups related options. Use heading or ListboxItemGroupLabel for a label.

PropTypeDefault
headingstring-
asChildboolean-
classNamestring-

ListboxItemGroupLabel

Label for a group. Must be used inside ListboxItemGroup.

PropTypeDefault
asChildboolean-
classNamestring-

ListboxValueText

Shows the selected value(s) as text. Use for custom trigger or display.

PropTypeDefault
placeholderstring-
asChildboolean-
classNamestring-

ListboxEmpty

Shown when the list has no items. Use for empty states.

PropTypeDefault
asChildboolean-
classNamestring-

ListboxShortcut

Optional keyboard shortcut hint shown next to an item.


For a complete list of props, see the Ark UI documentation.