# Listbox

URL: https://ark-ui.com/docs/components/listbox
LLM: https://ark-ui.com/llms.txt/components/listbox

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

---



## Anatomy

{/*  */}

```tsx
<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.

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const Basic = () => {
  const collection = createListCollection({
    items: [
      { label: 'United States', value: 'us' },
      { label: 'United Kingdom', value: 'uk' },
      { label: 'Canada', value: 'ca' },
      { label: 'Australia', value: 'au' },
      { label: 'Germany', value: 'de' },
      { label: 'France', value: 'fr' },
      { label: 'Japan', value: 'jp' },
    ],
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection}>
      <Listbox.Label className={styles.Label}>Select Country</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Controlled

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

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/listbox.module.css'

export const Controlled = () => {
  const collection = createListCollection({
    items: [
      { label: 'Small', value: 'sm' },
      { label: 'Medium', value: 'md' },
      { label: 'Large', value: 'lg' },
      { label: 'Extra Large', value: 'xl' },
    ],
  })
  const [value, setValue] = useState(['md'])

  return (
    <Listbox.Root
      className={styles.Root}
      collection={collection}
      value={value}
      onValueChange={(e) => setValue(e.value)}
    >
      <Listbox.Label className={styles.Label}>Select Size</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### 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.

```tsx
import { Listbox, createListCollection, useListbox } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/listbox.module.css'

export const RootProvider = () => {
  const collection = createListCollection({
    items: [
      { label: 'Low', value: 'low' },
      { label: 'Medium', value: 'medium' },
      { label: 'High', value: 'high' },
      { label: 'Critical', value: 'critical' },
    ],
  })
  const listbox = useListbox({ collection })

  return (
    <div className="stack">
      <button className={button.Root} onClick={() => listbox.setValue(['high'])}>
        Set to High
      </button>
      <Listbox.RootProvider className={styles.Root} value={listbox}>
        <Listbox.Label className={styles.Label}>Select Priority</Listbox.Label>
        <Listbox.Content className={styles.Content}>
          {collection.items.map((item) => (
            <Listbox.Item className={styles.Item} key={item.value} item={item}>
              <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
              <Listbox.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon />
              </Listbox.ItemIndicator>
            </Listbox.Item>
          ))}
        </Listbox.Content>
      </Listbox.RootProvider>
    </div>
  )
}
```

### Disabled Item

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

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const DisabledItem = () => {
  const collection = createListCollection({
    items: [
      { label: 'Free', value: 'free' },
      { label: 'Pro', value: 'pro' },
      { label: 'Enterprise', value: 'enterprise', disabled: true },
      { label: 'Custom', value: 'custom' },
    ],
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection}>
      <Listbox.Label className={styles.Label}>Select Plan</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

> 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.

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const Multiple = () => {
  const collection = createListCollection({
    items: [
      { label: 'Monday', value: 'mon' },
      { label: 'Tuesday', value: 'tue' },
      { label: 'Wednesday', value: 'wed' },
      { label: 'Thursday', value: 'thu' },
      { label: 'Friday', value: 'fri' },
      { label: 'Saturday', value: 'sat' },
      { label: 'Sunday', value: 'sun' },
    ],
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection} selectionMode="multiple">
      <Listbox.Label className={styles.Label}>Select Days</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Grouping

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

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const Group = () => {
  const collection = createListCollection({
    items: [
      { label: 'New York', value: 'nyc', region: 'North America' },
      { label: 'Los Angeles', value: 'lax', region: 'North America' },
      { label: 'Toronto', value: 'yyz', region: 'North America' },
      { label: 'London', value: 'lhr', region: 'Europe' },
      { label: 'Paris', value: 'cdg', region: 'Europe' },
      { label: 'Berlin', value: 'ber', region: 'Europe' },
      { label: 'Tokyo', value: 'nrt', region: 'Asia Pacific' },
      { label: 'Singapore', value: 'sin', region: 'Asia Pacific' },
      { label: 'Sydney', value: 'syd', region: 'Asia Pacific' },
    ],
    groupBy: (item) => item.region,
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection}>
      <Listbox.Label className={styles.Label}>Select Region</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.group().map(([region, items]) => (
          <Listbox.ItemGroup className={styles.ItemGroup} key={region}>
            <Listbox.ItemGroupLabel className={styles.ItemGroupLabel}>{region}</Listbox.ItemGroupLabel>
            {items.map((item) => (
              <Listbox.Item className={styles.Item} key={item.value} item={item}>
                <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
                <Listbox.ItemIndicator className={styles.ItemIndicator}>
                  <CheckIcon />
                </Listbox.ItemIndicator>
              </Listbox.Item>
            ))}
          </Listbox.ItemGroup>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Extended Selection

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

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const ExtendedSelect = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
      { label: 'Preact', value: 'preact' },
    ],
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection} selectionMode="extended">
      <Listbox.Label className={styles.Label}>
        Hold <kbd>⌘</kbd> or <kbd>Ctrl</kbd> to select multiple
      </Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Horizontal

Use the `orientation` prop to display the listbox items horizontally.

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const Horizontal = () => {
  const collection = createListCollection({
    items: [
      {
        title: 'Midnight Dreams',
        artist: 'Luna Ray',
        image: 'https://picsum.photos/seed/album1/300/300',
      },
      {
        title: 'Neon Skyline',
        artist: 'The Electric',
        image: 'https://picsum.photos/seed/album2/300/300',
      },
      {
        title: 'Acoustic Sessions',
        artist: 'Sarah Woods',
        image: 'https://picsum.photos/seed/album3/300/300',
      },
      {
        title: 'Urban Echoes',
        artist: 'Metro Collective',
        image: 'https://picsum.photos/seed/album4/300/300',
      },
      {
        title: 'Summer Vibes',
        artist: 'Coastal Waves',
        image: 'https://picsum.photos/seed/album5/300/300',
      },
    ],
    itemToValue: (item) => item.title,
    itemToString: (item) => item.title,
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection} orientation="horizontal">
      <Listbox.Label className={styles.Label}>Select Album</Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.ItemCard} key={item.title} item={item}>
            <Listbox.ItemIndicator className={styles.ItemCardIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
            <img className={styles.ItemCardImage} src={item.image} alt={item.title} />
            <span className={styles.ItemCardTitle}>{item.title}</span>
            <span className={styles.ItemCardArtist}>{item.artist}</span>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Grid Layout

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

```tsx
import { createGridCollection } from '@ark-ui/react/collection'
import { Listbox } from '@ark-ui/react/listbox'
import styles from 'styles/listbox.module.css'

export const Grid = () => {
  const collection = createGridCollection({
    items: [
      { label: '😀', value: 'grinning' },
      { label: '😍', value: 'heart-eyes' },
      { label: '🥳', value: 'partying' },
      { label: '😎', value: 'sunglasses' },
      { label: '🤩', value: 'star-struck' },
      { label: '😂', value: 'joy' },
      { label: '🥰', value: 'smiling-hearts' },
      { label: '😊', value: 'blush' },
      { label: '🤗', value: 'hugging' },
      { label: '😇', value: 'innocent' },
      { label: '🔥', value: 'fire' },
      { label: '✨', value: 'sparkles' },
      { label: '💯', value: 'hundred' },
      { label: '🎉', value: 'tada' },
      { label: '❤️', value: 'heart' },
      { label: '👍', value: 'thumbs-up' },
      { label: '👏', value: 'clap' },
      { label: '🚀', value: 'rocket' },
      { label: '⭐', value: 'star' },
      { label: '🌈', value: 'rainbow' },
    ],
    columnCount: 5,
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection}>
      <Listbox.Label className={styles.Label}>Pick a reaction</Listbox.Label>
      <Listbox.Content className={styles.GridContent}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.GridItem} key={item.value} item={item}>
            <Listbox.ItemText>{item.label}</Listbox.ItemText>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Filtering

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

```tsx
import { useListCollection } from '@ark-ui/react/collection'
import { Listbox } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import field from 'styles/field.module.css'
import styles from 'styles/listbox.module.css'

export const Filtering = () => {
  const { collection, filter } = useListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
      { label: 'Solid', value: 'solid' },
      { label: 'Next.js', value: 'nextjs' },
      { label: 'Nuxt.js', value: 'nuxtjs' },
      { label: 'Remix', value: 'remix' },
      { label: 'Gatsby', value: 'gatsby' },
      { label: 'Preact', value: 'preact' },
    ],
    filter: (itemText, filterText) => itemText.toLowerCase().includes(filterText.toLowerCase()),
  })

  return (
    <Listbox.Root className={styles.Root} collection={collection}>
      <Listbox.Label className={styles.Label}>Select Framework</Listbox.Label>
      <Listbox.Input
        className={field.Input}
        placeholder="Search frameworks..."
        onChange={(e) => filter(e.target.value)}
      />
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
        <Listbox.Empty className={styles.Empty}>No frameworks found</Listbox.Empty>
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Select All

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

```tsx
import { Listbox, createListCollection, useListboxContext } from '@ark-ui/react/listbox'
import { CheckIcon, MinusIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

const frameworks = createListCollection({
  items: [
    { label: 'React', value: 'react' },
    { label: 'Vue', value: 'vue' },
    { label: 'Angular', value: 'angular' },
    { label: 'Svelte', value: 'svelte' },
    { label: 'Next.js', value: 'nextjs' },
    { label: 'Nuxt.js', value: 'nuxtjs' },
    { label: 'Remix', value: 'remix' },
    { label: 'Gatsby', value: 'gatsby' },
  ],
})

const SelectAllHeader = () => {
  const listbox = useListboxContext()
  const isAllSelected = listbox.value.length === frameworks.items.length
  const isSomeSelected = listbox.value.length > 0 && listbox.value.length < frameworks.items.length

  const handleSelectAll = () => {
    if (isAllSelected) {
      listbox.setValue([])
    } else {
      listbox.setValue(frameworks.items.map((item) => item.value))
    }
  }

  return (
    <button className={styles.SelectAllHeader} type="button" onClick={handleSelectAll}>
      <span className={styles.SelectAllHeaderIndicator}>
        {isAllSelected ? <CheckIcon /> : isSomeSelected ? <MinusIcon /> : null}
      </span>
      <span className={styles.Label}>Select All</span>
    </button>
  )
}

export const SelectAll = () => {
  return (
    <Listbox.Root className={styles.Root} collection={frameworks} selectionMode="multiple">
      <SelectAllHeader />
      <Listbox.Content className={styles.Content}>
        {frameworks.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

### Value Text

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

```tsx
import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { CheckIcon } from 'lucide-react'
import styles from 'styles/listbox.module.css'

export const ValueText = () => {
  const collection = createListCollection({
    items: [
      { label: 'Red', value: 'red' },
      { label: 'Blue', value: 'blue' },
      { label: 'Green', value: 'green' },
      { label: 'Yellow', value: 'yellow' },
      { label: 'Purple', value: 'purple' },
    ],
  })

  return (
    <Listbox.Root
      className={styles.Root}
      collection={collection}
      selectionMode="multiple"
      defaultValue={['red', 'blue']}
    >
      <Listbox.Label className={styles.Label}>
        Colors: <Listbox.ValueText className={styles.ValueText} />
      </Listbox.Label>
      <Listbox.Content className={styles.Content}>
        {collection.items.map((item) => (
          <Listbox.Item className={styles.Item} key={item.value} item={item}>
            <Listbox.ItemText className={styles.ItemText}>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator className={styles.ItemIndicator}>
              <CheckIcon />
            </Listbox.ItemIndicator>
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}
```

## Guides

### Type Safety

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

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

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

```tsx
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

#### Props

**`collection`**
Type: `ListCollection<T>`
Required: true
Default Value: `undefined`
Description: The collection of items

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`defaultHighlightedValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The initial value of the highlighted item when opened.
Use when you don't need to control the highlighted value of the listbox.

**`defaultValue`**
Type: `string[]`
Required: false
Default Value: `[]`
Description: The initial default value of the listbox when rendered.
Use when you don't need to control the value of the listbox.

**`deselectable`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to disallow empty selection

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the listbox is disabled

**`disallowSelectAll`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to disallow selecting all items when `meta+a` is pressed

**`highlightedValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The controlled key of the highlighted item

**`id`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `Partial<{
  root: string
  content: string
  label: string
  item: (id: string | number) => string
  itemGroup: (id: string | number) => string
  itemGroupLabel: (id: string | number) => string
}>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the listbox. Useful for composition.

**`loopFocus`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to loop the keyboard navigation through the options

**`onHighlightChange`**
Type: `(details: HighlightChangeDetails<T>) => void`
Required: false
Default Value: `undefined`
Description: The callback fired when the highlighted item changes.

**`onSelect`**
Type: `(details: SelectionDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when an item is selected

**`onValueChange`**
Type: `(details: ValueChangeDetails<T>) => void`
Required: false
Default Value: `undefined`
Description: The callback fired when the selected item changes.

**`orientation`**
Type: `'horizontal' | 'vertical'`
Required: false
Default Value: `"vertical"`
Description: The orientation of the listbox.

**`scrollToIndexFn`**
Type: `(details: ScrollToIndexDetails) => void`
Required: false
Default Value: `undefined`
Description: Function to scroll to a specific index

**`selectionMode`**
Type: `SelectionMode`
Required: false
Default Value: `"single"`
Description: 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`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to select the item when it is highlighted

**`typeahead`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to enable typeahead on the listbox

**`value`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled keys of the selected items

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: root
**`data-orientation`**: The orientation of the listbox
**`data-disabled`**: Present when disabled

### Content

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Input

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoHighlight`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to automatically highlight the item when typing

**`keyboardPriority`**
Type: `'caret' | 'navigate'`
Required: false
Default Value: `"caret"`
Description: Determines how keyboard conflicts in the input are resolved.
- "caret": keep native text-editing behavior
- "navigate": forward supported keys to listbox navigation

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: input
**`data-disabled`**: Present when disabled

### ItemGroupLabel

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### ItemGroup

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: item-indicator
**`data-state`**: "checked" | "unchecked"

### Item

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`highlightOnHover`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to highlight the item on hover

**`item`**
Type: `any`
Required: false
Default Value: `undefined`
Description: The item to render

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: item-text
**`data-state`**: "checked" | "unchecked"
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: label
**`data-disabled`**: Present when disabled

### RootProvider

#### Props

**`value`**
Type: `UseListboxReturn<T>`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### ValueText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`placeholder`**
Type: `string`
Required: false
Default Value: `undefined`
Description: Text to display when no value is listboxed.

#### Data Attributes

**`data-scope`**: listbox
**`data-part`**: value-text
**`data-disabled`**: Present when disabled

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `empty` | `boolean` | Whether the select value is empty |
| `highlightedValue` | `string | null` | The value of the highlighted item |
| `highlightedItem` | `V | null` | The highlighted item |
| `highlightValue` | `(value: string) => void` | Function to highlight a value |
| `highlightFirst` | `VoidFunction` | Function to highlight the first value |
| `highlightLast` | `VoidFunction` | Function to highlight the last value |
| `highlightNext` | `VoidFunction` | Function to highlight the next value |
| `highlightPrevious` | `VoidFunction` | Function to highlight the previous 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) => ItemState` | Returns the state of a select item |
| `collection` | `ListCollection<V>` | Function to toggle the select |
| `disabled` | `boolean` | Whether the select is disabled |