Skip to content
Kappa
Autocomplete
@dicehub/kappav0.4.2

Autocomplete

A free-form text input with an accessible, filtered suggestion list.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const commands = [
  { label: "Run simulation", value: "run" },
  { label: "Review mesh", value: "mesh" },
  { label: "Restart worker", value: "restart", disabled: true },
  { label: "Open results", value: "results" },
];

const isItemDisabled = (item) => item.disabled === true;
</script>

<template>
  <Autocomplete
    :items="commands"
    :input-attrs="{ 'aria-label': 'Find a command' }"
    :is-item-disabled="isItemDisabled"
    clearable
    empty-text="No matching command."
    input-behavior="autohighlight"
    placeholder="Find a command..."
  />
</template>

Installation

Barrel

import {
  Autocomplete,
  createAutocompleteCollection,
} from "@dicehub/kappa";

Granular

import {
  Autocomplete,
  createAutocompleteCollection,
} from "@dicehub/kappa/components/autocomplete";

Usage

Pass items for the compact default UI, or compose the attached parts when suggestion markup needs more structure.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const commands = [
  { label: "Run simulation", value: "run" },
  { label: "Review mesh", value: "mesh" },
  { label: "Open results", value: "results" },
];
</script>

<template>
  <Autocomplete :items="commands">
    <Autocomplete.InputGroup
      aria-label="Find a command"
      placeholder="Find a command..."
    />
    <Autocomplete.Content teleport-to="body">
      <Autocomplete.Empty>No matching command.</Autocomplete.Empty>
      <Autocomplete.List>
        <template #default="{ item }">
          <Autocomplete.Item :item="item">
            {{ item.label }}
          </Autocomplete.Item>
        </template>
      </Autocomplete.List>
    </Autocomplete.Content>
  </Autocomplete>
</template>
Autocomplete accepts custom text by default. Use a Combobox or Select when the submitted value must come from a fixed list.

Composition

Typical part hierarchy
Autocomplete.Root
├── Autocomplete.Label
├── Autocomplete.InputGroup
└── Autocomplete.Content
    ├── Autocomplete.Empty
    └── Autocomplete.List
        ├── Autocomplete.Group
        │   ├── Autocomplete.GroupLabel
        │   └── Autocomplete.Item
        │       ├── Autocomplete.ItemText
        │       └── Autocomplete.ItemIndicator
        └── Autocomplete.Separator

InputGroup supplies the editable control and clear action. ComposeContent, List, groups, and items when suggestions need custom structure. Ark UI owns filtering state, keyboard navigation, focus, and ARIA relationships.

Examples

Controlled and Clearable

Bind v-model:input-value when surrounding UI needs the current text. The clear trigger appears only while text is present.

Input: empty

<script setup>
import { ref } from "vue";
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const inputValue = ref("");
const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Blueberry", value: "blueberry" },
  { label: "Pear", value: "pear" },
];
</script>

<template>
  <Autocomplete
    v-model:input-value="inputValue"
    :items="fruits"
    :input-attrs="{ 'aria-label': 'Type a fruit' }"
    clearable
    placeholder="Type a fruit..."
  />
  <p>Input: {{ inputValue || "empty" }}</p>
</template>

Field and Help Text

Use a visible label and forward aria-describedby through inputAttrsso assistive technology reaches the supporting text.

Start typing to filter countries.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const countries = [
  { label: "Germany", value: "de" },
  { label: "Japan", value: "jp" },
  { label: "United States", value: "us" },
];
</script>

<template>
  <Autocomplete
    :items="countries"
    :input-attrs="{ 'aria-describedby': 'country-help' }"
    label="Country"
    placeholder="Search countries..."
  />
  <p id="country-help">Start typing to filter countries.</p>
</template>

Invalid

Pair invalid with specific, visible error text. The state and relationship are forwarded to the Ark UI input.

Please enter a supported country.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const countries = [
  { label: "Germany", value: "de" },
  { label: "Japan", value: "jp" },
  { label: "United States", value: "us" },
];
</script>

<template>
  <Autocomplete
    :items="countries"
    :input-attrs="{ 'aria-describedby': 'country-error' }"
    invalid
    label="Country"
    placeholder="Search countries..."
  />
  <p id="country-error">Please enter a supported country.</p>
</template>

Grouped Suggestions

Group an advanced collection, then render each section from collection.group(). Filtering stays under application control.

<script setup>
import { computed, ref } from "vue";
import {
  Autocomplete,
  createAutocompleteCollection,
} from "@dicehub/kappa/components/autocomplete";

const query = ref("");
const regions = [
  { label: "US East", value: "us-east", group: "North America" },
  { label: "EU Central", value: "eu-central", group: "Europe" },
  { label: "AP Northeast", value: "ap-northeast", group: "Asia Pacific" },
];

const collection = computed(() =>
  createAutocompleteCollection({
    items: query.value.trim()
      ? regions.filter((item) =>
          item.label.toLowerCase().includes(query.value.trim().toLowerCase()),
        )
      : [],
    groupBy: (item) => item.group,
    itemToString: (item) => item.label,
    itemToValue: (item) => item.value,
  }),
);
</script>

<template>
  <Autocomplete v-model:input-value="query" :collection="collection">
    <Autocomplete.InputGroup
      aria-label="Find a region"
      placeholder="Find a region..."
    />
    <Autocomplete.Content>
      <Autocomplete.Empty>No matching region.</Autocomplete.Empty>
      <Autocomplete.List :render-items="false">
        <Autocomplete.Group
          v-for="[group, items] in collection.group()"
          :key="group"
        >
          <Autocomplete.GroupLabel>{{ group }}</Autocomplete.GroupLabel>
          <Autocomplete.Item v-for="item in items" :key="item.value" :item="item">
            {{ item.label }}
          </Autocomplete.Item>
        </Autocomplete.Group>
      </Autocomplete.List>
    </Autocomplete.Content>
  </Autocomplete>
</template>

Sizes

Choose a density from xs, sm, base, or lg.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Blueberry", value: "blueberry" },
];
</script>

<template>
  <Autocomplete size="xs" :items="fruits" :input-attrs="{ 'aria-label': 'Extra small' }" />
  <Autocomplete size="sm" :items="fruits" :input-attrs="{ 'aria-label': 'Small' }" />
  <Autocomplete size="base" :items="fruits" :input-attrs="{ 'aria-label': 'Base' }" />
  <Autocomplete size="lg" :items="fruits" :input-attrs="{ 'aria-label': 'Large' }" />
</template>

Custom Filtering

Supply a local predicate for domain-specific matching. This example also exposes the optional trigger and suggestions before typing.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const projects = [
  { label: "Aerofoil study", value: "aerofoil" },
  { label: "Cavity benchmark", value: "cavity" },
  { label: "Cylinder wake", value: "cylinder" },
];

const startsWith = (item, query) =>
  item.label.toLowerCase().startsWith(query.trim().toLowerCase());
</script>

<template>
  <Autocomplete
    :items="projects"
    :filter="startsWith"
    :input-attrs="{ 'aria-label': 'Filter projects' }"
    empty-text="No project starts with that text."
    placeholder="Filter projects..."
    show-on-empty
    show-trigger
  />
</template>

Disabled and Read-only

Disabled controls are unavailable. Read-only controls preserve a value and remain perceivable without accepting edits.

<script setup>
import { Autocomplete } from "@dicehub/kappa/components/autocomplete";

const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Blueberry", value: "blueberry" },
];
</script>

<template>
  <Autocomplete
    :items="fruits"
    disabled
    label="Disabled"
    placeholder="Unavailable"
  />
  <Autocomplete
    :items="fruits"
    :default-value="['apple']"
    label="Read only"
    read-only
  />
</template>

Accessibility

  • Ark UI supplies combobox semantics, active-descendant focus, and live option state.
  • Arrow Down and Arrow Up move through enabled suggestions.
  • Enter selects the highlighted suggestion; Escape closes the surface.
  • Disabled suggestions are announced but skipped during keyboard navigation.
  • Use a visible label and connect help or error text with inputAttrs.

The behavior layer follows theArk UI Combobox primitive.

API Reference

Autocomplete

Forwards remaining Ark UI root props, events, attributes, and listeners.

PropTypeDefaultDescription
itemsreadonly T[][]Items used by the convenience autocomplete UI.
collectionAutocompleteCollection<T>-Ark list collection used for advanced composition and grouping.
itemToString(item: T) => stringitem.label ?? String(item)Maps an item to visible and searchable text.
itemToValue(item: T) => stringitem.value ?? itemToString(item)Maps an item to its stable option value.
isItemDisabled(item: T) => booleanfalseMarks matching items unavailable; keyboard navigation skips them.
filterAutocompleteFilter<T>contains labelLocal filtering rule. Pass false when filtering externally.
showOnEmptybooleanfalseShows suggestions before the user enters a query.
emptyTextstring"No suggestions."Empty-state text for the convenience UI.
placeholderstring-Placeholder for the convenience input.
labelstring-Visible accessible label rendered above the convenience input.
lazyMountbooleanfalseDefers suggestion content mounting until the popup first opens.
unmountOnExitbooleanfalseUnmounts suggestion content after its exit transition.
inputAttrsAutocompleteInputAttributes{}Attributes forwarded to the internal input, including aria-describedby.
ariaLabelstring-Convenience accessible name for the internal input.
ariaDescribedbystring-Convenience relationship to supporting or error text.
clearablebooleanfalseShows the clear trigger only while the input has a value.
showTriggerbooleanfalseShows the optional suggestion trigger.
size"xs" | "sm" | "base" | "lg""base"Control height and text density.
allowCustomValuebooleantrueKeeps free-form text valid when it is not a suggestion.
closeOnSelectbooleantrueCloses the suggestions after selection.
disabledbooleanfalseDisables input and interaction.
readOnlybooleanfalseMakes the input non-editable while preserving its value.
invalidbooleanfalseMarks the control invalid for Ark state and styling.
inputBehavior"autohighlight" | "autocomplete" | "none""none"Controls automatic highlighting and inline completion behavior.
inputValuestring-Controlled input text.
defaultInputValuestring""Initial input text for uncontrolled usage.
modelValuestring[]-Controlled selected option values inherited from Ark UI.
defaultValuestring[][]Initial selected option values for uncontrolled usage.
positioningAutocompletePositioningOptionssame-width, viewport-safe bottom-startArk floating-position options with a 4px gutter and 8px overflow padding.

Autocomplete.Content

PropTypeDefaultDescription
teleportbooleantrueKeeps the surface in the local DOM tree when false.
teleportTostring | HTMLElement"body"Portal target for the positioned suggestion surface.

Events

EventDetailsDescription
@update:input-valuestringUpdates v-model:input-value with the current text.
@input-value-changeAutocompleteInputValueChangeDetailsProvides Ark input-change details.
@update:model-valuestring[]Updates v-model with the selected option values.
@value-changeAutocompleteValueChangeDetailsProvides details when selected option values change.
@update:openbooleanUpdates v-model:open with the suggestion-surface state.
@open-changeAutocompleteOpenChangeDetailsProvides details when the suggestion surface opens or closes.

Highlight, selection, focus-outside, interaction-outside, pointer-outside, and exit-complete events are forwarded from Ark UI as well.

Exports

ExportDescription
AutocompleteItems-driven autocomplete with the compound parts attached as properties.
AutocompleteRootNamed root export for the same component.
AutocompleteInputGroupInput control with optional clear and suggestion triggers.
AutocompleteContentPortalled, positioned suggestion surface.
AutocompleteListScrollable list with scoped item rendering.
AutocompleteItem / AutocompleteItemText / AutocompleteItemIndicatorSelectable suggestion and its text and selected-state parts.
AutocompleteEmptyEmpty state announced when no suggestion matches.
AutocompleteGroup / AutocompleteGroupLabel / AutocompleteSeparatorParts for grouped suggestion lists.
AutocompleteLabelArk-connected accessible field label.
createAutocompleteCollectionKappa alias for Ark createListCollection.
useAutocompleteCollectionKappa alias for Ark useListCollection.
AUTOCOMPLETE_SIZESReadonly list of supported size names.
Autocomplete* typesPublic props, slots, event details, collection, filter, item, and positioning types.