Ark Logo
GitHub
Components
Combobox

Combobox

A single input field that combines the functionality of a select and input.

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

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

const items = ref(['React', 'Solid', 'Vue'])
</script>

<template>
  <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>
    <Teleport to="body">
      <Combobox.Positioner>
        <Combobox.Content>
          <Combobox.ItemGroup>
            <Combobox.ItemGroupLabel>Frameworks</Combobox.ItemGroupLabel>
            <Combobox.Item v-for="item in items" :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.

<script setup lang="ts">
import { ref } from 'vue'
import { Combobox } from '@ark-ui/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" multiple>
    <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>
            <Combobox.ItemGroupLabel>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>

Using the Field Component

The Field component helps manage form-related state and accessibility attributes of a combobox. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

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

const items = ref(['React', 'Solid', 'Vue'])
</script>

<template>
  <Field.Root>
    <Combobox.Root :items="items">
      <Combobox.Label>Label</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.ClearTrigger>Clear</Combobox.ClearTrigger>
      </Combobox.Control>
      <Combobox.Positioner>
        <Combobox.Content>
          <Combobox.ItemGroup>
            <Combobox.ItemGroupLabel>Frameworks</Combobox.ItemGroupLabel>
            <Combobox.Item v-for="item in items" :key="item" :item="item">
              <Combobox.ItemText>{{ item }}</Combobox.ItemText>
              <Combobox.ItemIndicator>✓</Combobox.ItemIndicator>
            </Combobox.Item>
          </Combobox.ItemGroup>
        </Combobox.Content>
      </Combobox.Positioner>
    </Combobox.Root>
    <Field.HelperText>Additional Info</Field.HelperText>
    <Field.ErrorText>Error Info</Field.ErrorText>
  </Field.Root>
</template>

API Reference

Root

PropDefaultType
items
T[] | readonly T[]

The options of the select

allowCustomValue
boolean

Whether to allow typing custom values in the input

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
autoFocus
boolean

Whether to autofocus the input on mount

closeOnSelect
boolean

Whether to close the combobox when an item is selected.

compositetrue
boolean

Whether the combobox is a composed with other composite widgets like tabs

defaultOpen
boolean

The initial open state of the combobox when it is first rendered. Use when you do not need to control its open state.

defaultValue
string[]

The initial value of the combobox when it is first rendered. Use when you do not need to control the state of the combobox.

disabled
boolean

Whether the combobox is disabled

disableLayer
boolean

Whether to disable registering this a dismissable layer

form
string

The associate form of the combobox.

getSelectionValue
(details: SelectionValueDetails<T>) => string

Function to get the display value of the selected item

highlightedValue
string

The active item's id. Used to set the `aria-activedescendant` attribute

id
string

The unique identifier of the machine.

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

The ids of the elements in the combobox. Useful for composition.

inputBehavior'none'
'none' | 'autohighlight' | 'autocomplete'

Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated

inputValue
string

The current value of the combobox's input

invalid
boolean

Whether the combobox is invalid

isItemDisabled
(item: T) => boolean

Whether the item is disabled

itemToString
(item: T) => string

The label of the item

itemToValue
(item: T) => string

The value of the item

lazyMountfalse
boolean

Whether to enable lazy mounting

loopFocustrue
boolean

Whether to loop the keyboard navigation through the items

modelValue
string[]

multiple
boolean

Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container.

name
string

The `name` attribute of the combobox's input. Useful for form submission

open
boolean

Whether the combobox is open

openOnChangetrue
boolean | ((details: InputValueChangeDetails) => boolean)

Whether to show the combobox when the input value changes

openOnClickfalse
boolean

Whether to open the combobox popup on initial click on the input

openOnKeyPresstrue
boolean

Whether to open the combobox on arrow key press

placeholder
string

The placeholder text of the combobox's input

positioning
PositioningOptions

The positioning options to dynamically position the menu

readOnly
boolean

Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it

required
boolean

Whether the combobox is required

scrollToIndexFn
(details: ScrollToIndexDetails) => void

Function to scroll to a specific index

selectionBehavior'replace'
'replace' | 'clear' | 'preserve'

The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved

translations
IntlTranslations

Specifies the localized strings that identifies the accessibility elements and their states

unmountOnExitfalse
boolean

Whether to unmount on exit.

Data AttributeValue
[data-scope]combobox
[data-part]root
[data-invalid]Present when invalid
[data-readonly]Present when read-only

ClearTrigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Content

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]content
[data-state]"open" | "closed"

Control

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]control
[data-state]"open" | "closed"
[data-focus]Present when focused
[data-disabled]Present when disabled
[data-invalid]Present when invalid

Input

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]input
[data-invalid]Present when invalid
[data-state]"open" | "closed"

ItemGroupLabel

PropDefaultType
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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
id
string

ItemIndicator

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]item-indicator
[data-state]"checked" | "unchecked"

Item

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
item
any

The item to render

persistFocus
boolean

Whether hovering outside should clear the highlighted state

Data AttributeValue
[data-scope]combobox
[data-part]item
[data-highlighted]Present when highlighted
[data-state]"checked" | "unchecked"
[data-disabled]Present when disabled
[data-value]

ItemText

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]item-text
[data-disabled]Present when disabled
[data-highlighted]Present when highlighted

Label

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]combobox
[data-part]label
[data-readonly]Present when read-only
[data-disabled]Present when disabled
[data-invalid]Present when invalid
[data-focus]Present when focused

List

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Positioner

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

RootProvider

PropDefaultType
value
MachineApi<PropTypes, 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.
lazyMountfalse
boolean

Whether to enable lazy mounting

unmountOnExitfalse
boolean

Whether to unmount on exit.

Trigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
focusable
boolean

Whether the trigger is focusable

Data AttributeValue
[data-scope]combobox
[data-part]trigger
[data-state]"open" | "closed"
[data-focusable]
[data-readonly]Present when read-only
[data-disabled]Present when disabled

Accessibility

Complies with the Combobox WAI-ARIA design pattern.

Keyboard Support

KeyDescription
ArrowDown
When the combobox is closed, opens the listbox and highlights to the first option. When the combobox is open, moves focus to the next option.
ArrowUp
When the combobox is closed, opens the listbox and highlights to the last option. When the combobox is open, moves focus to the previous option.
Home
When the combobox is open, moves focus to the first option.
End
When the combobox is open, moves focus to the last option.
Escape
Closes the listbox.
Enter
Selects the highlighted option and closes the combobox.
Esc
Closes the combobox