Combobox

Combobox combines a text input with a role="listbox" popup. Users can filter options, navigate suggestions, and select a value. Use Select without text input.

Popup placement flips when preferred side lacks room, clamps to viewport, and follows anchor/content resize and ancestor scrolling.

Anatomy

• #option: Custom selectable option row content.
• #[option.slot]: Per-option render override.
• #tag: Selected tag content in multiple mode.
• #clear: Clear-button content.
• #create: Creatable row content.
• #group-label: Custom label row content.
• #empty: Empty state when filtering returns no selectable options.
• #loading: Loading state content.

The input, hidden form input, listbox, viewport, options, indicators, separators, and state attrs are generated by the component.

Usage

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "akaza-ui";

const value = ref("");
const options = [
  { value: "vue", label: "Vue" },
  { value: "nuxt", label: "Nuxt" },
];
</script>

<template>
  <Combobox v-model="value" :options="options" placeholder="Search stack" />
</template>

Examples

Controlled search

Bind v-model:search when search text must drive async loading or external filtering.

<script setup lang="ts">
const value = ref("");
const search = ref("");
</script>

<template>
  <Combobox v-model="value" v-model:search="search" :options="options" />
</template>

Multiple values

Set multiple and bind v-model to an array. clearable adds a clear control; selected values expose removable tags.

<template>
  <Combobox v-model="skills" multiple clearable :options="skillOptions" />
</template>

Custom filtering

Use filter when option search should use aliases, tags, or server-shaped data.

<template>
  <Combobox
    v-model="value"
    :options="options"
    :filter="(option, search) => String(option.keywords).includes(search)"
  />
</template>

Field integration

Place Combobox inside Field to inherit label metadata and form state.

<template>
  <Field label="Stack" name="stack" required>
    <Combobox v-model="stack" :options="options" />
  </Field>
</template>

Creatable options

Creation is app-controlled: Akaza emits requested text and your app decides whether and how to add it.

<Combobox
  v-model="framework"
  creatable
  :options="options"
  @create="value => options.push({ value, label: value })"
/>

Object values

Object values use identity by default. Supply isEqual when values are recreated and serializeValue when submitting them in a form.

<Combobox
  v-model="assignee"
  name="assignee"
  :options="people"
  :is-equal="(a, b) => a.id === b.id"
  :serialize-value="value => String(value.id)"
/>

Read-only and loading

readOnly preserves a visible value without allowing changes. loading exposes aria-busy and the loading slot for async sources.

<Combobox v-model="value" read-only :options="options" />
<Combobox v-model="value" loading :options="remoteOptions">
  <template #loading>Fetching teams…</template>
</Combobox>

Async results and composition

Result updates preserve the active option by value. If that option disappears, Combobox clears its active target. Enter during IME composition does not select an option.

Custom option slots retain component identity during ordinary updates, preserving local state and focus.

Native Form Reset

A native form reset restores the initial model and clears interaction state. Calling preventDefault() on the reset event preserves the current value. Reset updates v-model without emitting value-change.

API Reference

Props

Emits

Slots

UI Options

Styling Hooks

Popup transitions follow their placement side and last 120ms. Set --akaza-combobox-duration to change the duration. Reduced-motion mode removes the visible transition.

Keyboard