# Listbox

URL: https://ark-ui.com/docs/components/listbox
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/listbox.mdx

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

---

<ComponentPreview id="Listbox" />

## Anatomy

To set up the Listbox correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

{/* <Anatomy id="listbox" /> */}

## Examples

### Basic

Here's a basic example of the Listbox component.

<Example id="basic" />

### Controlled

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

<Example id="controlled" />

### Disabled Item

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

<Example id="disabled" />

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

### Multiple Selection

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

<Example id="multiple" />

### Grouping

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

<Example id="group" />

## Guides

### Type-Safety

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

This is particularly useful when building reusable listbox components with custom props and consistent styling.

```tsx
import { Listbox as ArkListbox, type CollectionItem } from '@ark-ui/react/listbox'
import { createListCollection } from '@ark-ui/react/collection'

interface ListboxProps<T extends CollectionItem> extends ArkListbox.RootProps<T> {}

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

Then, you can use the `Listbox` component as follows:

```tsx
const App = () => {
  const collection = createListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  })
  return (
    <Listbox
      collection={collection}
      onValueChange={(e) => {
        // this will be strongly typed Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Listbox>
  )
}
```

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultHighlightedValue` | `string` | No | 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[]` | No | The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox. |
| `deselectable` | `boolean` | No | Whether to disallow empty selection |
| `disabled` | `boolean` | No | Whether the listbox is disabled |
| `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the listbox. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | The callback fired when the highlighted item changes. |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | The callback fired when the selected item changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionMode` | `SelectionMode` | No | 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` | No | Whether to select the item when it is highlighted |
| `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox |
| `value` | `string[]` | No | The controlled keys of the selected items |


**Root Data Attributes:**

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


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing |


**Input Data Attributes:**

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


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

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


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover |
| `item` | `any` | No | The item to render |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

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


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseListboxReturn<T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no value is listboxed. |


**ValueText Data Attributes:**

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


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultHighlightedValue` | `string` | No | 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[]` | No | The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox. |
| `deselectable` | `boolean` | No | Whether to disallow empty selection |
| `disabled` | `boolean` | No | Whether the listbox is disabled |
| `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the listbox. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | The callback fired when the highlighted item changes. |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | The callback fired when the selected item changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionMode` | `SelectionMode` | No | 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` | No | Whether to select the item when it is highlighted |
| `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox |
| `value` | `string[]` | No | The controlled keys of the selected items |


**Root Data Attributes:**

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


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing |


**Input Data Attributes:**

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


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

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


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover |
| `item` | `any` | No | The item to render |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

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


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseListboxReturn<T>` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no value is selected. |


**ValueText Data Attributes:**

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


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultHighlightedValue` | `string` | No | 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[]` | No | The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox. |
| `deselectable` | `boolean` | No | Whether to disallow empty selection |
| `disabled` | `boolean` | No | Whether the listbox is disabled |
| `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the listbox. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `modelValue` | `string[]` | No | The model value of the listbox |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionMode` | `SelectionMode` | No | 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` | No | Whether to select the item when it is highlighted |
| `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox |


**Root Data Attributes:**

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


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

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


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No |  |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemIndicator Data Attributes:**

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


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover |
| `item` | `any` | No | The item to render |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

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


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `ListboxApi<PropTypes, T>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No |  |


**ValueText Data Attributes:**

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


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | `ListCollection<T>` | Yes | The collection of items |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `defaultHighlightedValue` | `string` | No | 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[]` | No | The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox. |
| `deselectable` | `boolean` | No | Whether to disallow empty selection |
| `disabled` | `boolean` | No | Whether the listbox is disabled |
| `disallowSelectAll` | `boolean` | No | Whether to disallow selecting all items when `meta+a` is pressed |
| `highlightedValue` | `string` | No | The controlled key of the highlighted item |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the listbox. Useful for composition. |
| `loopFocus` | `boolean` | No | Whether to loop the keyboard navigation through the options |
| `onHighlightChange` | `(details: HighlightChangeDetails<T>) => void` | No | The callback fired when the highlighted item changes. |
| `onSelect` | `(details: SelectionDetails) => void` | No | Function called when an item is selected |
| `onValueChange` | `(details: ValueChangeDetails<T>) => void` | No | The callback fired when the selected item changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the listbox. |
| `scrollToIndexFn` | `(details: ScrollToIndexDetails) => void` | No | Function to scroll to a specific index |
| `selectionMode` | `SelectionMode` | No | 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` | No | Whether to select the item when it is highlighted |
| `typeahead` | `boolean` | No | Whether to enable typeahead on the listbox |
| `value` | `string[]` | No | The controlled keys of the selected items |


**Root Data Attributes:**

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


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseListboxContext<T>]>` | Yes |  |


**Empty Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoHighlight` | `boolean` | No | Whether to automatically highlight the item when typing |
| `ref` | `Element` | No |  |


**Input Data Attributes:**

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


**ItemContext Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseListboxItemContext]>` | Yes |  |


**ItemGroupLabel Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ItemGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ItemGroup Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ItemIndicator Data Attributes:**

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


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `highlightOnHover` | `boolean` | No | Whether to highlight the item on hover |
| `item` | `any` | No | The item to render |
| `ref` | `Element` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ItemText Data Attributes:**

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


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Label Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseListboxReturn<T>` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ValueText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `placeholder` | `string` | No | Text to display when no value is selected. |


**ValueText Data Attributes:**

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


### Context

These are the properties available when using `Listbox.Context`, `useListboxContext` hook or `useListbox` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `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 |
