Combobox

Combobox combines a text input with a role="listbox" popup. Users type to filter options, move through suggestions with the keyboard, and select from a known set. Use Select when no text input is needed.

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>

API Reference

Props

Emits

Slots

UI Options

Styling Hooks

Popup entry and exit use a subtle side-aware structural transition. Override --akaza-combobox-duration to change its 120ms duration. Reduced-motion preference shortens it automatically.

Keyboard