║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: Listbox description: A component for creating keyboard-navigable selection lists and grids. preview: true links: api: /docs/components/listbox#api-reference

<ComponentTabs name="listbox-demo" />

Installation

@diceui/listbox

Installation with shadcn/ui

CLI

npx shadcn@latest add "https://diceui.com/r/listbox"

Manual

<Steps> <Step> Install the following dependencies:

 ```package-install
 @diceui/listbox
 ```

</Step> <Step> Copy and paste the following code into your project.

<ComponentSource name="listbox" />

</Step> </Steps>

Layout

Import the parts, and compose them together.

import * as Listbox from "@diceui/listbox"

<Listbox.Root>
  <Listbox.Group>
    <Listbox.GroupLabel/>
    <Listbox.Item >
      <Listbox.ItemIndicator />
    </Listbox.Item>
  </Listbox.Group>
</Listbox.Root>

Examples

Horizontal Orientation

Set orientation="horizontal" to create a horizontally navigable list.

<ComponentTabs name="listbox-horizontal-demo" />

Grid Layout

For grid layouts, use orientation="mixed" to enable navigation in both directions. Use CSS Grid to arrange the items in a grid structure. In grid layouts, arrow keys will navigate accordingly:

• Up/Down: Navigates within a column
• Left/Right: Navigates within a row

<ComponentTabs name="listbox-grid-demo" />

Grouped Items

Group items together to create a list of related options.

<ComponentTabs name="listbox-group-demo" />

API Reference

Root

The root component for creating listboxes.

<AutoTypeTable path="./types/docs/listbox.ts" name="RootProps" />

Group

A group of items inside the selectable list.

<AutoTypeTable path="./types/docs/listbox.ts" name="GroupProps" />

GroupLabel

A label for the group of items.

<AutoTypeTable path="./types/docs/listbox.ts" name="GroupLabelProps" />

Item

An item inside the selectable list.

<AutoTypeTable path="./types/docs/listbox.ts" name="ItemProps" />

ItemIndicator

A visual indicator that shows when the item is selected.

<AutoTypeTable path="./types/docs/listbox.ts" name="ItemIndicatorProps" />

Accessibility

Keyboard Interactions

<KeyboardShortcutsTable shortcuts={[ { keys: ["Tab"], description: "Focuses the last active item in the list.", }, { keys: ["Shift + Tab"], description: "Moves focus to previous focusable item in the list.", }, { keys: ["ArrowUp"], description: "Moves highlighting to previous item in vertical lists.", }, { keys: ["ArrowDown"], description: "Moves highlighting to next item in vertical lists.", }, { keys: ["ArrowLeft"], description: "Moves highlighting to previous item in horizontal lists.", }, { keys: ["ArrowRight"], description: "Moves highlighting to next item in horizontal lists.", }, ]} />

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║