Listbox

Usage

import { Listbox } from "@chakra-ui/react"

<Listbox.Root>
  <Listbox.Label />
  <Listbox.Content>
    <Listbox.Item>
      <Listbox.ItemText />
      <Listbox.ItemIndicator />
    </Listbox.Item>
  </Listbox.Content>
</Listbox.Root>

To setup the listbox, use useListCollection to manage the list collection.

Examples

Controlled

Control the listbox value externally using the value and onValueChange props for custom state management.

With Store

An alternative way to control the listbox is to use the RootProvider component and the useListbox store hook.

This way you can access the listbox state and methods from outside the listbox.

Use RootProvider + useListbox or Root, not both.

Disabled Item

Disable specific items in the listbox to indicate unavailable options while keeping them visible for context.

Grouped

Use item groups to organize related options with clear section headers, making it easier for users to find specific categories of items.

Horizontal

Display listbox items in a horizontal layout with card-based presentation, perfect for media galleries or visual selection interfaces.

Multiple Selection

Enable users to select multiple items from the list, useful for scenarios like choosing tags, categories, or preferences.

Select All

Provide convenient "Select All" and "Select None" controls for multiple selection scenarios, with visual indicators showing selection state.

Extended Select

Use extended selection mode to allow users to select multiple items using keyboard shortcuts like Cmd/Ctrl for advanced selection patterns.

With Checkmark

Display custom checkmarks for multiple selection scenarios, providing clear visual feedback for selected items.

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.

With Input

Combine a search input with the listbox to filter options dynamically, making it easy to find specific items in long lists.

With Popover

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

With Dialog

Present the listbox in a modal dialog for focused selection experiences, particularly useful for important choices that need user attention.

Virtualized

Handle large datasets efficiently with virtualization, rendering only visible items to maintain smooth scrolling performance even with thousands of items.

Image Explorer

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

Transfer List

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

Emoji Grid

Display emojis in a grid layout with filtering capability, perfect for emoji pickers or icon selection interfaces.

Props

Root

Label

Input

Content

Item

ItemText

ItemIndicator

ItemGroup

ItemGroupLabel

Explorer

Explore the Listbox component parts interactively. Click on parts in the sidebar to highlight them in the preview.