Sections

Components

Utilities

Forms

Hooks

useIsMobile

Listbox

Copy Markdown

Select a single or multiple items from a list.

Docs API

PreviewCode

Brazil

Mexico

Ireland

Installation#

CLIManual

pnpmbunnpmyarn

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.

PreviewCode

Selected the Large size

Small

Medium

Large

Extra Large

❌

States#

Disabled#

Disable the entire listbox with the disabled prop.

PreviewCode

Brazil

Mexico

Ireland

Orientation#

Use orientation prop to change the orientation of the listbox.

Horizontal#

PreviewCode

Favorite album

Rappa Mundi

O Rappa

Acústico MTV

Charlie Brown Jr.

Thriller

Michael Jackson

The Eminem Show

Eminem

Selection Mode#

Multiple#

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

PreviewCode

Brazil

Mexico

Ireland

Extended#

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

PreviewCode

Hold ⌘ or Ctrl to select multiple

Brazil

Mexico

Ireland

None#

Set selectionMode="none" to disable selection.

PreviewCode

Actions

New file Create a new file ⌘N

Edit file Make changes ⌘E

Danger zone

Delete file Move to trash ⌘D

Examples#

With Icon#

PreviewCode

🇧🇷 Brazil

🇲🇽 Mexico

🇮🇪 Ireland

With Description#

PreviewCode

Brazil South America's country, Portuguese speaking.

Mexico North America's country, Spanish speaking.

Ireland Europe's country, Irish/English speaking.

Image Explorer#

PreviewCode

Mountain Landscape

Ocean Waves

Forest Path

City Skyline

Desert Dunes

Mountain Landscape

Scenic mountain view

Transfer List#

PreviewCode

Available

Brazil

Ireland

Selected

Mexico

Grouping#

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

PreviewCode

South America

Brazil

Colombia

North America

Mexico

Canada

With Filter#

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

PreviewCode

Brazil

Mexico

Ireland

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

PreviewCode

Select framework

Grid Layout#

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

PreviewCode

😀

😍

🥳

😎

🤩

😂

🥰

😊

🤗

😇

🔥

✨

💯

🎉

❤️

👍

👏

🚀

⭐

🌈

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"
`orientation`	`"vertical"	"horizontal"`
`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"`
`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 ](/docs/components/link-overlay)[

Marquee ](/docs/components/marquee)

On This Page

Installation Anatomy Usage Controlled States Disabled Orientation Horizontal Selection Mode Multiple Extended None Examples With Icon With Description Image Explorer Transfer List Grouping With Filter With Popover Grid Layout API Reference Listbox ListboxContent ListboxItem ListboxItemText ListboxItemIndicator ListboxItemGroup ListboxItemGroupLabel ListboxValueText ListboxEmpty ListboxShortcut