Combobox | Ark UI

Framework

Anatomy

To set up the combobox 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

Learn how to use the Combobox component in your project. Let’s take a look at the most basic example

import { Combobox, Portal } from '@ark-ui/react'

const Basic = () => {
  const items = ['React', 'Solid', 'Vue']
  return (
    <Combobox.Root items={items} lazyMount unmountOnExit>
      <Combobox.Label>Framework</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content>
            <Combobox.ItemGroup id="framework">
              <Combobox.ItemGroupLabel htmlFor="framework">Frameworks</Combobox.ItemGroupLabel>
              {items.map((item) => (
                <Combobox.Item key={item} item={item}>
                  <Combobox.ItemText>{item}</Combobox.ItemText>
                  <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
                </Combobox.Item>
              ))}
            </Combobox.ItemGroup>
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.Root>
  )
}

import { Combobox } from '@ark-ui/solid'
import { For } from 'solid-js'
import { Portal } from 'solid-js/web'

const Basic = () => {
  const items = ['React', 'Solid', 'Vue']
  return (
    <Combobox.Root items={items}>
      <Combobox.Label>Framework</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content>
            <Combobox.ItemGroup id="framework">
              <Combobox.ItemGroupLabel for="framework">Frameworks</Combobox.ItemGroupLabel>
              <For each={items}>
                {(item) => (
                  <Combobox.Item item={item}>
                    <Combobox.ItemText>{item}</Combobox.ItemText>
                    <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
                  </Combobox.Item>
                )}
              </For>
            </Combobox.ItemGroup>
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.Root>
  )
}

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

const basicItems = ref(['React', 'Solid', 'Vue'])

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

<template>
  <Combobox.Root :items="basicItems">
    <Combobox.Label>Framework</Combobox.Label>
    <Combobox.Control>
      <Combobox.Input />
      <Combobox.Trigger>Open</Combobox.Trigger>
      <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
    </Combobox.Control>
    <Teleport to="body">
      <Combobox.Positioner>
        <Combobox.Content>
          <Combobox.ItemGroup id="framework">
            <Combobox.ItemGroupLabel htmlFor="framework">Frameworks</Combobox.ItemGroupLabel>
            <Combobox.Item v-for="item in basicItems" :key="item" :item="item">
              <Combobox.ItemText>{{ item }}</Combobox.ItemText>
              <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
            </Combobox.Item>
          </Combobox.ItemGroup>
        </Combobox.Content>
      </Combobox.Positioner>
    </Teleport>
  </Combobox.Root>
</template>

Advanced Customization

Extended example that shows usage with complex item objects, including disabled state for certain options.

import { Combobox, Portal } from '@ark-ui/react'

const Advanced = () => {
  const items: Item[] = [
    { label: 'React', value: 'react' },
    { label: 'Solid', value: 'solid' },
    { label: 'Vue', value: 'vue' },
    { label: 'Svelte', value: 'svelte', disabled: true },
  ]
  return (
    <Combobox.Root items={items}>
      <Combobox.Label>Framework</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content>
            <Combobox.ItemGroup id="framework">
              <Combobox.ItemGroupLabel htmlFor="framework">Frameworks</Combobox.ItemGroupLabel>
              {items.map((item) => (
                <Combobox.Item key={item.value} item={item}>
                  <Combobox.ItemText>{item.label}</Combobox.ItemText>
                  <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
                </Combobox.Item>
              ))}
            </Combobox.ItemGroup>
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.Root>
  )
}

import { Combobox } from '@ark-ui/solid'
import { For } from 'solid-js'
import { Portal } from 'solid-js/web'

const Advanced = () => {
  const items: Item[] = [
    { label: 'React', value: 'react' },
    { label: 'Solid', value: 'solid' },
    { label: 'Vue', value: 'vue' },
    { label: 'Svelte', value: 'svelte', disabled: true },
  ]
  return (
    <Combobox.Root items={items}>
      <Combobox.Label>Framework</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner>
          <Combobox.Content>
            <Combobox.ItemGroup id="framework">
              <Combobox.ItemGroupLabel for="framework">Frameworks</Combobox.ItemGroupLabel>
              <For each={items}>
                {(item) => (
                  <Combobox.Item item={item}>
                    <Combobox.ItemText>{item.label}</Combobox.ItemText>
                    <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
                  </Combobox.Item>
                )}
              </For>
            </Combobox.ItemGroup>
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.Root>
  )
}

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

const basicItems = ref(['React', 'Solid', 'Vue'])

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

<template>
  <Combobox.Root :items="advancedItems">
    <Combobox.Label>Framework</Combobox.Label>
    <Combobox.Control>
      <Combobox.Input />
      <Combobox.Trigger>Open</Combobox.Trigger>
      <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
    </Combobox.Control>
    <Teleport to="body">
      <Combobox.Positioner>
        <Combobox.Content>
          <Combobox.ItemGroup id="framework">
            <Combobox.ItemGroupLabel htmlFor="framework">Frameworks</Combobox.ItemGroupLabel>
            <Combobox.Item v-for="item in advancedItems" :key="item.value" :item="item">
              <Combobox.ItemText>{{ item.label }}</Combobox.ItemText>
              <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
            </Combobox.Item>
          </Combobox.ItemGroup>
        </Combobox.Content>
      </Combobox.Positioner>
    </Teleport>
  </Combobox.Root>
</template>

API Reference

Root

Prop	Type	Default
`items`	`T[] \| readonly T[]`
`allowCustomValue`	`boolean`
`asChild`	`boolean`
`autoFocus`	`boolean`
`closeOnSelect`	`boolean`
`defaultValue`	`string[]`
`dir`	`'ltr' \| 'rtl'`	`"ltr"`
`disabled`	`boolean`
`form`	`string`
`getRootNode`	`() => Node \| ShadowRoot \| Document`
`highlightedValue`	`string`
`id`	`string`
`ids`	`Partial<{ root: string label: string control: string input: string content: string trigger: string clearTrigger: string item(id: string, index?: number \| undefined): string positioner: string itemGroup(id: string \| number): string itemGroupLabel(id: string \| number): string }>`
`inputBehavior`	`'none' \| 'autohighlight' \| 'autocomplete'`
`inputValue`	`string`
`invalid`	`boolean`
`isItemDisabled`	`(item: T) => boolean`
`itemToString`	`(item: T) => string`
`itemToValue`	`(item: T) => string`
`lazyMount`	`boolean`	`false`
`loop`	`boolean`
`multiple`	`boolean`
`name`	`string`
`onExitComplete`	`() => void`
`onFocusOutside`	`(event: FocusOutsideEvent) => void`
`onHighlightChange`	`(details: HighlightChangeDetails<T>) => void`
`onInputValueChange`	`(details: InputValueChangeDetails) => void`
`onInteractOutside`	`(event: InteractOutsideEvent) => void`
`onOpenChange`	`(details: OpenChangeDetails) => void`
`onPointerDownOutside`	`(event: PointerDownOutsideEvent) => void`
`onValueChange`	`(details: ValueChangeDetails<T>) => void`
`openOnClick`	`boolean`
`placeholder`	`string`
`positioning`	`PositioningOptions`
`present`	`boolean`
`readOnly`	`boolean`
`selectionBehavior`	`'replace' \| 'clear' \| 'preserve'`
`selectOnBlur`	`boolean`
`translations`	`IntlTranslations`
`unmountOnExit`	`boolean`	`false`
`value`	`string[]`

Item

Prop	Type	Default
`asChild`	`boolean`
`item`	`any`

Input

Prop	Type	Default
`asChild`	`boolean`

Label

Prop	Type	Default
`asChild`	`boolean`

Content

Prop	Type	Default
`asChild`	`boolean`

Control

Prop	Type	Default
`asChild`	`boolean`

Trigger

Prop	Type	Default
`asChild`	`boolean`

ItemText

Prop	Type	Default
`asChild`	`boolean`

ItemGroup

Prop	Type	Default
`id`	`string`
`asChild`	`boolean`

Positioner

Prop	Type	Default
`asChild`	`boolean`

ClearTrigger

Prop	Type	Default
`asChild`	`boolean`

ItemIndicator

Prop	Type	Default
`asChild`	`boolean`

ItemGroupLabel

Prop	Type	Default
`htmlFor`	`string`
`asChild`	`boolean`