Select

Select renders a trigger and a role="listbox" popup. It supports single or multiple values, labels, separators, typeahead, cancelable changes, and Field metadata without a nested subcomponent tree.

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

Use it when the user must choose from a known list. Use autocomplete when the same select needs lightweight filtering. Use Combobox when the text input itself is the primary interaction.

Anatomy

• #trigger: Custom trigger content. Use triggerProps when rendering your own interactive trigger.
• #value: Selected value content inside the trigger.
• #option: Content inside each generated role="option" row.
• #group-label: Content for non-selectable label rows.

The trigger, listbox, options, indicator, separators, and hidden native select are generated by the component. Style those generated parts with the matching ui keys.

Usage

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

const plan = ref("pro");
const options = [
  { value: "free", label: "Free" },
  { value: "pro", label: "Pro" },
  { value: "team", label: "Team", disabled: true },
];
</script>

<template>
  <Select v-model="plan" :options="options" placeholder="Choose plan" />
</template>

Examples

Multiple selection

Set multiple and bind v-model to string[]. Selected options stay open so users can toggle more than one item.

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

const permissions = ref(["read"]);
const options = [
  { value: "read", label: "Read" },
  { value: "write", label: "Write" },
  { value: "deploy", label: "Deploy" },
];
</script>

<template>
  <Select v-model="permissions" multiple :options="options" />
</template>

Grouped options

Use type: "label" and type: "separator" for non-selectable rows. They are skipped by keyboard navigation.

<template>
  <Select
    v-model="role"
    :options="[
      { type: 'label', label: 'Project' },
      { value: 'viewer', label: 'Viewer' },
      { value: 'editor', label: 'Editor' },
      { type: 'separator' },
      { type: 'label', label: 'Admin' },
      { value: 'owner', label: 'Owner' },
    ]"
  />
</template>

Autocomplete filtering

Set autocomplete to render a search input inside the popup. Focus moves into the search input when opened; that input owns aria-activedescendant and Arrow/Enter/Escape navigation. Bind v-model:search when search text should drive async loading or external filtering.

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

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

<template>
  <Select
    v-model="value"
    v-model:search="search"
    autocomplete
    :options="options"
    search-placeholder="Filter options"
  />
</template>

Field integration

Place Select inside Field to inherit id, name, required, disabled state, invalid state, and aria-describedby. Required/native invalid state is revealed after selection, blur, or invalid submit; it is not shown on initial render.

<template>
  <Field label="Server region" name="region" required>
    <Select v-model="region" :options="regions" placeholder="Choose region" />
  </Field>
</template>

Custom option row

Use #option to render richer option content. The component still owns role="option", selection state, highlighting, and click handling.

<template>
  <Select v-model="region" :options="regions">
    <template #option="{ label, description, isSelected }">
      <span aria-hidden="true">{{ isSelected ? "✓" : "" }}</span>
      <span>
        <strong>{{ label }}</strong>
        <small>{{ description }}</small>
      </span>
    </template>
  </Select>
</template>

Cancel a selection

value-change fires before the model changes. Call details.cancel() to block a value.

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

API Reference

Props

Emits

Slots

Option Shape

UI Options

Styling Hooks

Plain class applies to the root wrapper. Use ui.trigger, ui.content, and ui.option for internal parts.

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

Native data-akaza-invalid appears after interaction or invalid submit. Controlled invalid state from the invalid prop or parent Field appears immediately.

Keyboard