Listbox

A component for selecting a single or multiple items from a list.

Anatomy

<Listbox.Root>
  <Listbox.Label />
  <Listbox.Content>
    <Listbox.ItemGroup>
      <Listbox.ItemGroupLabel />
      <Listbox.Item>
        <Listbox.ItemText />
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.ItemGroup>
  </Listbox.Content>
  <Listbox.ValueText />
</Listbox.Root>

Examples

Basic

Here's a basic example of the Listbox component.

Controlled

The Listbox component can be controlled by using the value and onValueChange props. This allows you to manage the selected value externally.

Root Provider

An alternative way to control the listbox is to use the RootProvider component and the useListbox hook. This way you can access the state and methods from outside the component.

Disabled Item

Listbox items can be disabled using the disabled prop on the collection item.

You can also use the isItemDisabled within the createListCollection to disable items based on a condition.

Multiple

You can set the selectionMode property as multiple to allow the user to select multiple items at a time.

Grouping

The Listbox component supports grouping items. You can use the groupBy function to group items based on a specific property.

Extended Selection

The extended selection mode allows users to select multiple items using keyboard modifiers like Cmd (Mac) or Ctrl (Windows/Linux).

Horizontal

Use the orientation prop to display the listbox items horizontally.

Grid Layout

Use createGridCollection to display items in a grid layout with keyboard navigation support.

Filtering

Use useListCollection with the filter function to enable filtering of items.

Select All

Use useListboxContext to implement a "Select All" functionality that allows users to select or deselect all items at once.

Value Text

Use Listbox.ValueText to display the selected values as a comma-separated string.

Guides

Type Safety

The Listbox.RootComponent type enables you to create typed wrapper components that maintain full type safety for collection items.

const Listbox: ArkListbox.RootComponent = (props) => {
  return <ArkListbox.Root {...props}>{/* ... */}</ArkListbox.Root>
}

Use the wrapper with full type inference on onValueChange and other callbacks:

const App = () => {
  const collection = createListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
    ],
  })
  return (
    <Listbox
      collection={collection}
      onValueChange={(e) => {
        // e.items is typed as Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Listbox>
  )
}

API Reference

Props

Root

Prop	Default	Type
`collection`		`ListCollection<T>` The collection of items
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`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.
`defaultValue`	`[]`	`string[]` The initial default value of the listbox when rendered. Use when you don't need to control the 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.
`loopFocus`	`false`	`boolean` Whether to loop the keyboard navigation through the options
`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.
`orientation`	`'vertical'`	`'horizontal' \| 'vertical'` The orientation of the listbox.
`scrollToIndexFn`		`(details: ScrollToIndexDetails) => void` Function to scroll to a specific index
`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.
`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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	root
`[data-orientation]`	The orientation of the listbox
`[data-disabled]`	Present when disabled

Content

Renders a <div> element.

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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	content
`[data-activedescendant]`	The id the active descendant of the content
`[data-orientation]`	The orientation of the content
`[data-layout]`
`[data-empty]`	Present when the content is empty

CSS Variable	Description
`--column-count`	The column count value for the Content

Empty

Renders a <div> element.

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

Input

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`autoHighlight`	`false`	`boolean` Whether to automatically highlight the item when typing

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	input
`[data-disabled]`	Present when disabled

ItemGroupLabel

Renders a <div> element.

Prop	Default	Type
`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

Renders a <div> element.

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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	item-group
`[data-disabled]`	Present when disabled
`[data-orientation]`	The orientation of the item
`[data-empty]`	Present when the content is empty

ItemIndicator

Renders a <div> element.

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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	item-indicator
`[data-state]`	"checked" \| "unchecked"

Item

Renders a <div> element.

Prop	Default	Type
`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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	item
`[data-value]`	The value of the item
`[data-selected]`	Present when selected
`[data-layout]`
`[data-state]`	"checked" \| "unchecked"
`[data-orientation]`	The orientation of the item
`[data-highlighted]`	Present when highlighted
`[data-disabled]`	Present when disabled

ItemText

Renders a <div> element.

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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	item-text
`[data-state]`	"checked" \| "unchecked"
`[data-disabled]`	Present when disabled
`[data-highlighted]`	Present when highlighted

Label

Renders a <label> element.

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

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	label
`[data-disabled]`	Present when disabled

RootProvider

Prop	Default	Type
`value`		`UseListboxReturn<T>`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ValueText

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`placeholder`		`string` Text to display when no value is listboxed.

Attribute	Description
`[data-scope]`	listbox
`[data-part]`	value-text
`[data-disabled]`	Present when disabled

Context

API

Property	Type
`empty`	`boolean` Whether the select value is empty
`highlightedValue`	`string` The value of the highlighted item
`highlightedItem`	`V` The highlighted item
`highlightValue`	`(value: string) => void` Function to highlight a value
`clearHighlightedValue`	`VoidFunction` Function to clear the highlighted value
`selectedItems`	`V[]` The selected items
`hasSelectedItems`	`boolean` Whether there's a selected option
`value`	`string[]` The selected item keys
`valueAsString`	`string` The string representation of the selected items
`selectValue`	`(value: string) => void` Function to select a value
`selectAll`	`VoidFunction` Function to select all values. Note: This should only be called when the selectionMode is `multiple` or `extended`. Otherwise, an exception will be thrown.
`setValue`	`(value: string[]) => void` Function to set the value of the select
`clearValue`	`(value?: string) => void` Function to clear the value of the select. If a value is provided, it will only clear that value, otherwise, it will clear all values.
`getItemState`	`(props: ItemProps<any>) => ItemState` Returns the state of a select item
`collection`	`ListCollection<V>` Function to toggle the select
`disabled`	`boolean` Whether the select is disabled