Combobox

Filter a collection with text, move through matches, and accept one result.

Usage

Prefix

Filter items whose labels begin with the current query.

Add an environment

<!-- Combobox / Prefix -->
<script setup lang="ts">
import { ComboboxRoot, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty } from '@sectile/vue/combobox'
const environments = [
  { id: 'production', label: 'Production', detail: 'customer.app' },
  { id: 'staging', label: 'Staging', detail: 'staging.customer.app' },
  { id: 'development', label: 'Development', detail: 'Local workspace' },
]
const environmentIDs = environments.map(({ id }) => id)
const environmentLabel = (id: string) => environments.find(item => item.id === id)?.label ?? id

</script>

<template>
  <ComboboxRoot :items="environmentIDs" :text-value="environmentLabel" default-input-value="pro">
    <ComboboxInput placeholder="Search environments" />
    <ComboboxContent>
      <ComboboxItem v-for="item in environments" :key="item.id" :value="item.id">
        <strong>{{ item.label }}</strong>
        <small>{{ item.detail }}</small>
      </ComboboxItem>
      <ComboboxEmpty>No matching environment</ComboboxEmpty>
    </ComboboxContent>
  </ComboboxRoot>
</template>

Contains

Filter items whose labels contain the query instead of only matching its prefix.

Add an environment

<!-- Combobox / Contains -->
<script setup lang="ts">
import { ComboboxRoot, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty } from '@sectile/vue/combobox'
const environments = [
  { id: 'production', label: 'Production', detail: 'customer.app' },
  { id: 'staging', label: 'Staging', detail: 'staging.customer.app' },
  { id: 'development', label: 'Development', detail: 'Local workspace' },
]
const environmentIDs = environments.map(({ id }) => id)
const environmentLabel = (id: string) => environments.find(item => item.id === id)?.label ?? id

</script>

<template>
  <ComboboxRoot :items="environmentIDs" :text-value="environmentLabel" default-input-value="pro">
    <ComboboxInput placeholder="Search environments" />
    <ComboboxContent>
      <ComboboxItem v-for="item in environments" :key="item.id" :value="item.id">
        <strong>{{ item.label }}</strong>
        <small>{{ item.detail }}</small>
      </ComboboxItem>
      <ComboboxEmpty>No matching environment</ComboboxEmpty>
    </ComboboxContent>
  </ComboboxRoot>
</template>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

Add an environment

<!-- Combobox / Controlled -->
<script setup lang="ts">
import { ComboboxRoot, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty } from '@sectile/vue/combobox'
const environments = [
  { id: 'production', label: 'Production', detail: 'customer.app' },
  { id: 'staging', label: 'Staging', detail: 'staging.customer.app' },
  { id: 'development', label: 'Development', detail: 'Local workspace' },
]
const environmentIDs = environments.map(({ id }) => id)
const environmentLabel = (id: string) => environments.find(item => item.id === id)?.label ?? id

</script>

<template>
  <ComboboxRoot :items="environmentIDs" :text-value="environmentLabel" default-input-value="pro">
    <ComboboxInput placeholder="Search environments" />
    <ComboboxContent>
      <ComboboxItem v-for="item in environments" :key="item.id" :value="item.id">
        <strong>{{ item.label }}</strong>
        <small>{{ item.detail }}</small>
      </ComboboxItem>
      <ComboboxEmpty>No matching environment</ComboboxEmpty>
    </ComboboxContent>
  </ComboboxRoot>
</template>

Examples

IME

Keep composition text separate until an IME commit produces the accepted query.

Add an environment

<!-- Combobox / Ime -->
<script setup lang="ts">
import { ComboboxRoot, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty } from '@sectile/vue/combobox'
const environments = [
  { id: 'production', label: 'Production', detail: 'customer.app' },
  { id: 'staging', label: 'Staging', detail: 'staging.customer.app' },
  { id: 'development', label: 'Development', detail: 'Local workspace' },
]
const environmentIDs = environments.map(({ id }) => id)
const environmentLabel = (id: string) => environments.find(item => item.id === id)?.label ?? id

</script>

<template>
  <ComboboxRoot :items="environmentIDs" :text-value="environmentLabel" default-input-value="pro">
    <ComboboxInput placeholder="Search environments" />
    <ComboboxContent>
      <ComboboxItem v-for="item in environments" :key="item.id" :value="item.id">
        <strong>{{ item.label }}</strong>
        <small>{{ item.detail }}</small>
      </ComboboxItem>
      <ComboboxEmpty>No matching environment</ComboboxEmpty>
    </ComboboxContent>
  </ComboboxRoot>
</template>

Floating positioning

This component uses the shared positioning engine. Use the live positioning example to change side, align, offsets, collision boundaries, strategy, and tracking while inspecting the resolved placement.

API

Vue package: @sectile/vue/combobox

Components

ComboboxRoot
ComboboxInput
ComboboxContent
ComboboxItem
ComboboxEmpty

Props

`ComboboxRootProps`

align: TypePositionAlignDefault'start'
Alignment of positioned content relative to its anchor.
as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
avoidCollisions: TypebooleanDefaulttrue
Whether positioned content may flip or shift to remain visible.
collisionBoundary: TypePositionBoundaryDefaultundefined
Boundary used to keep positioned content visible.
collisionPadding: TypePositionPaddingDefault8
Space kept between positioned content and its collision boundary.
defaultInputValue: TypestringDefault''
Initial uncontrolled text shown by the editable input.
defaultOpen: TypebooleanDefaultfalse
Initial uncontrolled open state.
defaultValue: Typestring | nullDefaultnull
Initial value used when the component owns its state.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
hideWhenDetached: TypebooleanDefaultfalse
Whether positioned content hides when its anchor leaves the layout.
inputValue: TypestringDefaultundefined
Controlled text currently shown by the editable input.
items: Typereadonly ComboboxItemDefinition<string>[]DefaultRequired
Ordered item values managed by the component.
label: TypestringDefaultundefined
Accessible name announced for the control.
modelValue: Typestring | nullDefaultundefined
Current value when state is controlled by the parent.
open: TypebooleanDefaultundefined
Whether the associated popup or disclosure is open.
policies: TypeComboboxPolicies<string>Defaultundefined
Behavior policies that customize validation, movement, or selection.
position: TypebooleanDefaulttrue
Whether the popup is positioned relative to its trigger.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
side: TypePositionSideDefault'bottom'
Preferred side of the anchor for positioned content.
sideOffset: TypenumberDefault8
Distance between positioned content and its anchor.
strategy: TypePositionStrategyDefault'absolute'
CSS positioning strategy used for anchored content.
tracking: TypePositionTrackingDefault'events'
Update strategy used while anchored content is open.

`ComboboxItemProps`

as: TypePrimitiveAsDefaultundefined
Element or component rendered for this part.
asChild: TypebooleanDefaultundefined
Whether to merge this part into its single child instead of rendering a wrapper.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
value: TypestringDefaultRequired
Current value exposed by this contract.

`ComboboxPartProps`

as: TypePrimitiveAsDefaultVaries by part
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.

Slots

`ComboboxRootSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlightedValue: Typestring | null
Value currently highlighted for interaction.
inputValue: Typestring
Current editable input text.
open: Typeboolean
Whether the associated popup or disclosure is open.
readonly: Typeboolean
Whether the value can be inspected but not changed.
value: Typestring | null
Current value exposed by this contract.

`ComboboxItemSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlighted: Typeboolean
Whether this item is highlighted for interaction.
selected: Typeboolean
Whether this item is selected.
value: Typestring
Current value exposed by this contract.

Events

`ComboboxRoot`

accept: Payloadstring
Emitted when the current draft becomes an accepted value.
highlight: Payloadstring | null
Emitted when the highlighted item changes.
update:inputValue: Payloadstring
Emitted when editable input text changes.
update:modelValue: Payloadstring | null
Emitted when the component requests a new controlled value.
update:open: Payloadboolean
Emitted when the component requests a new open state.

Other types

`ComboboxValueChangeHandler`

type ComboboxValueChangeHandler = (value: string | null) => void

`ComboboxInputValueChangeHandler`

type ComboboxInputValueChangeHandler = (value: string) => void

`ComboboxOpenChangeHandler`

type ComboboxOpenChangeHandler = (value: boolean) => void

`ComboboxHighlightHandler`

type ComboboxHighlightHandler = (value: string | null) => void

`ComboboxAcceptHandler`

type ComboboxAcceptHandler = (value: string) => void

Parts

Shared scope: [data-scope="combobox"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`input`	`[data-part="input"]`	Accepts the editable value or draft.	—
`content`	`[data-part="content"]`	Contains the component content shown for the active state.	—
`item`	`[data-part="item"]`	Represents one selectable or actionable item.	—
`empty`	`[data-part="empty"]`	Shows feedback when no collection item matches.	—

Keyboard interaction

Key	Behavior
`Arrow Down` / `Arrow Up`	Open the popup and move the active option.
`Enter`	Accept the active option.
`Escape`	Close the popup without replacing the accepted value.
`Text input`	Filter options without breaking IME composition.

Accessibility

The input exposes autocomplete, expanded state, popup ownership, and the active descendant while options expose selection.

See the corresponding WAI-ARIA pattern for the host accessibility contract.

Combobox ​

Usage ​

Prefix ​

Contains ​

Controlled ​

Examples ​

IME ​

Floating positioning ​

API ​

Props ​

ComboboxRootProps ​

ComboboxItemProps ​

ComboboxPartProps ​

Slots ​

ComboboxRootSlotProps ​

ComboboxItemSlotProps ​

Events ​

ComboboxRoot ​

Other types ​

ComboboxValueChangeHandler ​

ComboboxInputValueChangeHandler ​

ComboboxOpenChangeHandler ​

ComboboxHighlightHandler ​

ComboboxAcceptHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​

Combobox

Usage

Prefix

Contains

Controlled

Examples

IME

Floating positioning

API

Props

`ComboboxRootProps`

`ComboboxItemProps`

`ComboboxPartProps`

Slots

`ComboboxRootSlotProps`

`ComboboxItemSlotProps`

Events

`ComboboxRoot`

Other types

`ComboboxValueChangeHandler`

`ComboboxInputValueChangeHandler`

`ComboboxOpenChangeHandler`

`ComboboxHighlightHandler`

`ComboboxAcceptHandler`

Parts

Keyboard interaction

Accessibility