useCombobox

A headless combobox primitive — an editable text input paired with a popup listbox — implementing the WAI-ARIA combobox with listbox popup pattern: type to filter, navigate with the keyboard via active-descendant, and pick a single option. It owns the behavior (open/close, filtering, the highlight, selection, and the full keyboard) and the ARIA wiring as ready-to-bind prop bags; you own the markup and styles.

This is the Vue binding; the framework-agnostic core lives in @oriui/headless, and the styled OriCombobox is built on it. useDialog and useDisclosure lean on a native platform element; a combobox has no native primitive, so useCombobox's default is the core state machine + prop-getters. Like the overlays it still resolves through the OriHeadless contract, so an app can swap a custom / Zag-backed engine — the native core adapter is simply the default. It is the first behavior to fully exercise the @oriui/headless engine.

Import

import { useCombobox } from '@oriui/headless/vue'

Options

Pass an options object — or a getter returning one, to stay reactive (the styled component passes () => ({ … })). options, disabled, and filter are read live; id, defaultValue and defaultInputValue are read once at setup.

Each option is a ComboboxItem — value is the stable identity, label is what the input shows:

interface ComboboxItem {
    value: string
    label: string
    disabled?: boolean
}

Returns

A control object — the reactive state plus the prop bags you bind to each part. Every *Props value is a ComputedRef; bind it with v-bind. The get* / set* and the action members are plain functions.

Usage

Bind each part's prop bag with v-bind, render items, and pass the same index you iterate with into getOptionProps:

<script setup lang="ts">
import { useCombobox } from '@oriui/headless/vue'

const cb = useCombobox(() => ({
    options: [
        { label: 'Apple', value: 'apple' },
        { label: 'Banana', value: 'banana' },
        { label: 'Cherry', value: 'cherry' }
    ]
}))
</script>

<template>
    <div v-bind="cb.rootProps.value">
        <label v-bind="cb.labelProps.value">Fruit</label>

        <div v-bind="cb.controlProps.value">
            <input v-bind="cb.inputProps.value" placeholder="Search a fruit…" @blur="cb.setOpen(false)" />
            <button v-bind="cb.triggerProps.value">▾</button>

            <ul v-bind="cb.listboxProps.value">
                <li
                    v-for="(item, index) in cb.items.value"
                    :key="item.value"
                    v-bind="cb.getOptionProps(item, index)"
                    :data-selected="cb.getOptionState(item).selected"
                >
                    {{ item.label }}
                </li>
            </ul>
        </div>
    </div>
</template>

Accessibility

Implements the WAI-ARIA combobox with listbox popup pattern; the prop bags carry the wiring.

• inputProps set role="combobox" with aria-autocomplete="list", autocomplete="off", aria-expanded, and aria-controls pointing at the listbox; the highlighted option is referenced by aria-activedescendant — focus never leaves the input, so no roving tabindex is needed.
• listboxProps set role="listbox", aria-labelledby (the element you bind labelProps to), and hidden while closed. Options from getOptionProps are role="option" with aria-selected; a disabled item carries aria-disabled and is skipped by keyboard navigation. Each option also exposes data-highlighted (active) and data-state="checked|unchecked" for styling.
• triggerProps / clearTriggerProps are tabindex="-1" buttons (the input keeps focus) with accessible labels ("Open / Close suggestions", "Clear selection"); the trigger also carries aria-expanded / aria-controls.
• Selecting an option reflects its label into the input and closes the list. The machine does not dismiss on blur or on a press outside — wire that yourself, with setOpen(false) on the input's blur (as the example does) or with useDismissable (as the styled component does); Tab therefore moves focus away but does not itself close the list.
• Option ids are derived from the position in items, so always pass the same index you iterate items with into getOptionProps(item, index), or aria-activedescendant will point at the wrong row.

See also

• @oriui/headless — the framework-agnostic contract and the core state machine.
• OriCombobox — the styled component built on this primitive.
• useDialog · useDisclosure · useTheme — the other headless primitives.
• CSS layer — the standalone .ori-combobox classes for the parts.