Listbox

Listbox displays a persistent list for single or multiple selection. It supports grouped rows, typeahead, range selection, filtering, object values, native forms, and virtualization.

Use Select for a popup or Combobox for text input with suggestions.

Anatomy

• #option: Custom content for every selectable row.
• #group-label: Custom content for rows with type: "label".
• #empty: Content shown when filtering leaves no selectable options.

The component owns role="listbox", option roles, selection/highlight state, hidden form inputs, and keyboard behavior. Style those generated parts with the matching ui keys.

Usage

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

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

<template>
  <Listbox v-model="framework" :options="options" aria-label="Framework" />
</template>

Examples

Multiple selection

Set multiple and bind an array. Ctrl+A or Cmd+A selects every enabled visible option; Shift+Arrow extends a keyboard range.

<template>
  <Listbox
    v-model="permissions"
    multiple
    :options="[
      { value: 'read', label: 'Read' },
      { value: 'write', label: 'Write' },
      { value: 'deploy', label: 'Deploy' },
    ]"
    aria-label="Permissions"
  />
</template>

Group labels and separators

Rows with type: "label" or type: "separator" remain non-selectable and are skipped by keyboard navigation.

<template>
  <Listbox
    v-model="tool"
    :options="[
      { type: 'label', label: 'Frameworks' },
      { value: 'vue', label: 'Vue' },
      { value: 'nuxt', label: 'Nuxt' },
      { type: 'separator' },
      { type: 'label', label: 'Tooling' },
      { value: 'vite', label: 'Vite' },
    ]"
    aria-label="Tool"
  />
</template>

Filtering

Set filterable to render a search input above the list. Bind v-model:search for external state or use filter for custom matching.

<script setup lang="ts">
import { ref } from "vue";

const search = ref("");
</script>

<template>
  <Listbox
    v-model="framework"
    v-model:search="search"
    filterable
    :options="options"
    filter-placeholder="Filter frameworks"
    aria-label="Framework"
  />
</template>

Large data sets

Set virtualize to render a bounded window with VueUse. Provide a stable row height; group and separator rows should use the same height in virtual mode.

<template>
  <Listbox
    v-model="result"
    virtualize
    :virtual-height="240"
    :virtual-item-height="40"
    :overscan="6"
    :options="results"
    aria-label="Search results"
  />
</template>

Object values

Use by to compare objects and serializeValue to control submitted form values. The model keeps the original object.

<template>
  <Listbox
    v-model="assignee"
    name="assignee"
    by="id"
    :serialize-value="user => String(user.id)"
    :options="users.map(user => ({ value: user, label: user.name }))"
    aria-label="Assignee"
  />
</template>

Field integration

Inside Field, Listbox inherits id, name, required/disabled/invalid state, and description/error IDs. Required invalid state appears after blur or an invalid submit, not on initial render.

<template>
  <Field label="Environment" name="environment" required>
    <Listbox v-model="environment" :options="environments" />
  </Field>
</template>

Cancel a change

Change events fire before state updates. Call details.cancel() to keep the current value, search, or highlight.

<template>
  <Listbox
    v-model="role"
    :options="roles"
    @value-change="(value, details) => value === 'owner' && details.cancel()"
  />
</template>

Virtualized focus

Initial focus scrolls a distant selected option into view. Manual scrolling remains under user control. Listbox removes aria-activedescendant while its active virtual row is unmounted.

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

Models

Props

Emits

Slots

Exposed Methods

Option Shape

UI Options

Styling Hooks

Plain class applies to the root wrapper. Use ui.content and ui.option for the list and rows.

Keyboard