Listbox

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

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.

Examples

Basic

Here's a basic example of the Listbox component.

import { Listbox, createListCollection } from '@ark-ui/react/listbox'

export const Basic = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })

  return (
    <Listbox.Root collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        {collection.items.map((item) => (
          <Listbox.Item key={item} item={item}>
            <Listbox.ItemText>{item}</Listbox.ItemText>
            <Listbox.ItemIndicator />
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}

import { Listbox, createListCollection } from '@ark-ui/solid/listbox'
import { Index } from 'solid-js'

export const Basic = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })

  return (
    <Listbox.Root collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        <Index each={collection.items}>
          {(item) => (
            <Listbox.Item item={item()}>
              <Listbox.ItemText>{item()}</Listbox.ItemText>
              <Listbox.ItemIndicator />
            </Listbox.Item>
          )}
        </Index>
      </Listbox.Content>
    </Listbox.Root>
  )
}

<script setup lang="ts">
import { Listbox, createListCollection } from '@ark-ui/vue/listbox'

const collection = createListCollection({
  items: ['React', 'Solid', 'Vue'],
})
</script>

<template>
  <Listbox.Root :collection="collection">
    <Listbox.Label>Framework</Listbox.Label>
    <Listbox.Content>
      <Listbox.Item v-for="item in collection.items" :key="item" :item="item">
        <Listbox.ItemText>{{ item }}</Listbox.ItemText>
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.Content>
  </Listbox.Root>
</template>

Controlled

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

import { Listbox, createListCollection } from '@ark-ui/react/listbox'
import { useState } from 'react'

export const Controlled = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })
  const [value, setValue] = useState(['React'])

  return (
    <Listbox.Root value={value} onValueChange={(e) => setValue(e.value)} collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        {collection.items.map((item) => (
          <Listbox.Item key={item} item={item}>
            <Listbox.ItemText>{item}</Listbox.ItemText>
            <Listbox.ItemIndicator />
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}

import { Listbox, createListCollection } from '@ark-ui/solid/listbox'
import { Index, createSignal } from 'solid-js'

export const Controlled = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })
  const [value, setValue] = createSignal(['React'])

  return (
    <Listbox.Root value={value()} onValueChange={(e) => setValue(e.value)} collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        <Index each={collection.items}>
          {(item) => (
            <Listbox.Item item={item()}>
              <Listbox.ItemText>{item()}</Listbox.ItemText>
              <Listbox.ItemIndicator />
            </Listbox.Item>
          )}
        </Index>
      </Listbox.Content>
    </Listbox.Root>
  )
}

<script setup lang="ts">
import { Listbox, createListCollection } from '@ark-ui/vue/listbox'
import { ref } from 'vue'

const collection = createListCollection({
  items: ['React', 'Solid', 'Vue'],
})
const value = ref(['React'])
</script>

<template>
  <Listbox.Root :collection="collection" v-model="value">
    <Listbox.Label>Framework</Listbox.Label>
    <Listbox.Content>
      <Listbox.Item v-for="item in collection.items" :key="item" :item="item">
        <Listbox.ItemText>{{ item }}</Listbox.ItemText>
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.Content>
  </Listbox.Root>
</template>

Disabled Item

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

import { Listbox, createListCollection } from '@ark-ui/react/listbox'

export const Disabled = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Svelte', value: 'svelte', disabled: true },
      { label: 'Vue', value: 'vue' },
    ],
  })

  return (
    <Listbox.Root collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        {collection.items.map((item) => (
          <Listbox.Item key={item.value} item={item}>
            <Listbox.ItemText>{item.label}</Listbox.ItemText>
            <Listbox.ItemIndicator />
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}

import { Listbox, createListCollection } from '@ark-ui/solid/listbox'
import { Index } from 'solid-js'

export const Disabled = () => {
  const collection = createListCollection({
    items: [
      { label: 'React', value: 'react' },
      { label: 'Solid', value: 'solid' },
      { label: 'Svelte', value: 'svelte', disabled: true },
      { label: 'Vue', value: 'vue' },
    ],
  })

  return (
    <Listbox.Root collection={collection}>
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        <Index each={collection.items}>
          {(item) => (
            <Listbox.Item item={item()}>
              <Listbox.ItemText>{item().label}</Listbox.ItemText>
              <Listbox.ItemIndicator />
            </Listbox.Item>
          )}
        </Index>
      </Listbox.Content>
    </Listbox.Root>
  )
}

<script setup lang="ts">
import { Listbox, createListCollection } from '@ark-ui/vue/listbox'

const collection = createListCollection({
  items: [
    { label: 'React', value: 'react' },
    { label: 'Solid', value: 'solid' },
    { label: 'Svelte', value: 'svelte', disabled: true },
    { label: 'Vue', value: 'vue' },
  ],
})
</script>

<template>
  <Listbox.Root :collection="collection">
    <Listbox.Label>Select your Framework</Listbox.Label>
    <Listbox.Content>
      <Listbox.Item v-for="item in collection.items" :key="item.value" :item="item">
        <Listbox.ItemText>{{ item.label }}</Listbox.ItemText>
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.Content>
  </Listbox.Root>
</template>

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.

import { Listbox, createListCollection } from '@ark-ui/react/listbox'

export const Multiple = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })

  return (
    <Listbox.Root collection={collection} selectionMode="multiple">
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        {collection.items.map((item) => (
          <Listbox.Item key={item} item={item}>
            <Listbox.ItemText>{item}</Listbox.ItemText>
            <Listbox.ItemIndicator />
          </Listbox.Item>
        ))}
      </Listbox.Content>
    </Listbox.Root>
  )
}

import { Listbox, createListCollection } from '@ark-ui/solid/listbox'
import { Index } from 'solid-js'

export const Multiple = () => {
  const collection = createListCollection({ items: ['React', 'Solid', 'Vue'] })

  return (
    <Listbox.Root collection={collection} selectionMode="multiple">
      <Listbox.Label>Select your Framework</Listbox.Label>
      <Listbox.Content>
        <Index each={collection.items}>
          {(item) => (
            <Listbox.Item item={item()}>
              <Listbox.ItemText>{item()}</Listbox.ItemText>
              <Listbox.ItemIndicator />
            </Listbox.Item>
          )}
        </Index>
      </Listbox.Content>
    </Listbox.Root>
  )
}

<script setup lang="ts">
import { Listbox, createListCollection } from '@ark-ui/vue/listbox'

const collection = createListCollection({
  items: ['React', 'Solid', 'Vue'],
})
</script>

<template>
  <Listbox.Root :collection="collection" selectionMode="multiple">
    <Listbox.Label>Select your Framework</Listbox.Label>
    <Listbox.Content>
      <Listbox.Item v-for="item in collection.items" :key="item" :item="item">
        <Listbox.ItemText>{{ item }}</Listbox.ItemText>
        <Listbox.ItemIndicator />
      </Listbox.Item>
    </Listbox.Content>
  </Listbox.Root>
</template>