Listbox

Used to display a list of options for selection.

AI TipWant to skip the docs? Use the MCP Server

Select framework

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>

Examples

Controlled

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

Select framework

Selected: []

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.

Select framework

Selected: []

Disabled Item

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

Select framework

Grouped

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

Select media

Horizontal

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

Select Album

Multiple Selection

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

Select frameworks (multiple)

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.

Select frameworks (hold ⌘ or ^ to select multiple)

With Checkmark

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

Select frameworks (with checkmarks)

With Icon

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

Select framework

With Description

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

Select framework

With Input

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

Select Framework

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.

Select Country (249 items)

Image Explorer

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

Mountain Landscape

Scenic mountain view

Prop	Default	Type
`collection` *		`ListCollection<T>` The collection of items
`defaultValue`	`[]`	`string[]` The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox.
`loopFocus`	`false`	`boolean` Whether to loop the keyboard navigation through the options
`orientation`	`'vertical'`	`'horizontal' \| 'vertical'` The orientation of the listbox.
`selectionMode`	`'single'`	`SelectionMode` How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys.
`colorPalette`	`gray`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` The color palette of the component
`variant`	`subtle`	`'subtle' \| 'solid' \| 'plain'` The variant of the component
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`unstyled`		`boolean` Whether to remove the component's style.
`defaultHighlightedValue`		`string` The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox.
`deselectable`		`boolean` Whether to disallow empty selection
`disabled`		`boolean` Whether the listbox is disabled
`disallowSelectAll`		`boolean` Whether to disallow selecting all items when `meta+a` is pressed
`highlightedValue`		`string` The controlled key of the highlighted item
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string content: string label: string item: (id: string \| number) => string itemGroup: (id: string \| number) => string itemGroupLabel: (id: string \| number) => string }>` The ids of the elements in the listbox. Useful for composition.
`onHighlightChange`		`(details: HighlightChangeDetails<T>) => void` The callback fired when the highlighted item changes.
`onSelect`		`(details: SelectionDetails) => void` Function called when an item is selected
`onValueChange`		`(details: ValueChangeDetails<T>) => void` The callback fired when the selected item changes.
`scrollToIndexFn`		`(details: ScrollToIndexDetails) => void` Function to scroll to a specific index
`selectOnHighlight`		`boolean` Whether to select the item when it is highlighted
`typeahead`		`boolean` Whether to enable typeahead on the listbox
`value`		`string[]` The controlled keys of the selected items

Label

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Content

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Item

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`highlightOnHover`		`boolean` Whether to highlight the item on hover
`item`		`any` The item to render

ItemText

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ItemIndicator

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ItemGroup

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ItemGroupLabel

Prop	Default	Type
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Explorer

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

Select item

Component Anatomy

Hover to highlight, click to select parts

label

input

item

itemText

itemIndicator

itemGroup

itemGroupLabel

content

root

valueText

empty

listbox.recipe.ts

Combobox

Select

Listbox

Usage

Examples

Controlled

With Store

Disabled Item

Grouped

Horizontal

Multiple Selection

Select All

Extended Select

With Checkmark

With Icon

With Description

With Input

With Popover

With Dialog

Virtualized

Image Explorer

Transfer List

Emoji Grid

Props

Root

Label

Content

Item

ItemText

ItemIndicator

ItemGroup

ItemGroupLabel

Explorer

Component Anatomy

Listbox

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}Usage

Component Anatomy

Usage