Sections

Utilities

Forms

Hooks

useIsMobileNew

Listbox

Select a single or multiple items from a list.

Installation


pnpm dlx shadcn@latest add @shark/listbox

Anatomy


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

Usage


import { createListCollection } from "@ark-ui/react";
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.

Selected the Large size

❌

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.

Hold ⌘ or Ctrl to select multiple

None

Set selectionMode="none" to disable selection.

Examples

With Icon

With Description

Image Explorer

Mountain Landscape

Scenic mountain view

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.

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.

Prop	Type	Default
`collection`	`ListCollection<T>`	required
`value`	`string[]`	-
`defaultValue`	`string[]`	`[]`
`onValueChange`	`(details: ValueChangeDetails<T>) => void`	-
`selectionMode`	`"single" \| "multiple" \| "extended"`	`"single"`
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`
`disabled`	`boolean`	-
`deselectable`	`boolean`	-
`loopFocus`	`boolean`	`false`

ListboxContent

Holds the list of options.

Prop	Type	Default
`asChild`	`boolean`	-
`className`	`string`	-

ListboxItem

A single selectable list option.

Prop	Type	Default
`item`	`T`	required
`variant`	`"default" \| "destructive"`	`"default"`
`asChild`	`boolean`	-
`highlightOnHover`	`boolean`	-

ListboxItemText

Text content for a list item.

Prop	Type	Default
`asChild`	`boolean`	-
`className`	`string`	-

ListboxItemIndicator

Checkmark or icon shown when the item is selected.

Prop	Type	Default
`children`	`ReactNode`	`CheckIcon`
`asChild`	`boolean`	-
`className`	`string`	-

ListboxItemGroup

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

Prop	Type	Default
`heading`	`string`	-
`asChild`	`boolean`	-
`className`	`string`	-

ListboxItemGroupLabel

Label for a group. Must be used inside ListboxItemGroup.

Prop	Type	Default
`asChild`	`boolean`	-
`className`	`string`	-

ListboxValueText

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

Prop	Type	Default
`placeholder`	`string`	-
`asChild`	`boolean`	-
`className`	`string`	-

ListboxEmpty

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

Prop	Type	Default
`asChild`	`boolean`	-
`className`	`string`	-

ListboxShortcut

Optional keyboard shortcut hint shown next to an item.

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

Link Overlay

Marquee