Sections

Utilities

Listbox

Select a single or multiple items from a list.

Installation


pnpm dlx shadcn@latest add https://shark.vini.one/r/listbox.json

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

❌

State

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

Add icons to listbox items to provide visual context and improve recognition of different options.

With Description

Include additional descriptive text for each item to provide more context and help users make informed choices.

Image Explorer

Create an interactive gallery where the listbox acts as navigation for displaying different images or media content.

Mountain Landscape

Scenic mountain view

Transfer List

Create a dual-listbox interface for moving items between available and selected states, commonly used for permission management or item selection workflows.

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 (e.g. no search results).

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.