<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>Composition
Autocomplete.Root
├── Autocomplete.Label
├── Autocomplete.InputGroup
└── Autocomplete.Content
├── Autocomplete.Empty
└── Autocomplete.List
├── Autocomplete.Group
│ ├── Autocomplete.GroupLabel
│ └── Autocomplete.Item
│ ├── Autocomplete.ItemText
│ └── Autocomplete.ItemIndicator
└── Autocomplete.SeparatorInputGroup 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.
<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.
<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.
| Prop | Type | Default | Description |
|---|---|---|---|
items | readonly T[] | [] | Items used by the convenience autocomplete UI. |
collection | AutocompleteCollection<T> | - | Ark list collection used for advanced composition and grouping. |
itemToString | (item: T) => string | item.label ?? String(item) | Maps an item to visible and searchable text. |
itemToValue | (item: T) => string | item.value ?? itemToString(item) | Maps an item to its stable option value. |
isItemDisabled | (item: T) => boolean | false | Marks matching items unavailable; keyboard navigation skips them. |
filter | AutocompleteFilter<T> | contains label | Local filtering rule. Pass false when filtering externally. |
showOnEmpty | boolean | false | Shows suggestions before the user enters a query. |
emptyText | string | "No suggestions." | Empty-state text for the convenience UI. |
placeholder | string | - | Placeholder for the convenience input. |
label | string | - | Visible accessible label rendered above the convenience input. |
lazyMount | boolean | false | Defers suggestion content mounting until the popup first opens. |
unmountOnExit | boolean | false | Unmounts suggestion content after its exit transition. |
inputAttrs | AutocompleteInputAttributes | {} | Attributes forwarded to the internal input, including aria-describedby. |
ariaLabel | string | - | Convenience accessible name for the internal input. |
ariaDescribedby | string | - | Convenience relationship to supporting or error text. |
clearable | boolean | false | Shows the clear trigger only while the input has a value. |
showTrigger | boolean | false | Shows the optional suggestion trigger. |
size | "xs" | "sm" | "base" | "lg" | "base" | Control height and text density. |
allowCustomValue | boolean | true | Keeps free-form text valid when it is not a suggestion. |
closeOnSelect | boolean | true | Closes the suggestions after selection. |
disabled | boolean | false | Disables input and interaction. |
readOnly | boolean | false | Makes the input non-editable while preserving its value. |
invalid | boolean | false | Marks the control invalid for Ark state and styling. |
inputBehavior | "autohighlight" | "autocomplete" | "none" | "none" | Controls automatic highlighting and inline completion behavior. |
inputValue | string | - | Controlled input text. |
defaultInputValue | string | "" | Initial input text for uncontrolled usage. |
modelValue | string[] | - | Controlled selected option values inherited from Ark UI. |
defaultValue | string[] | [] | Initial selected option values for uncontrolled usage. |
positioning | AutocompletePositioningOptions | same-width, viewport-safe bottom-start | Ark floating-position options with a 4px gutter and 8px overflow padding. |
Autocomplete.Content
| Prop | Type | Default | Description |
|---|---|---|---|
teleport | boolean | true | Keeps the surface in the local DOM tree when false. |
teleportTo | string | HTMLElement | "body" | Portal target for the positioned suggestion surface. |
Events
| Event | Details | Description |
|---|---|---|
@update:input-value | string | Updates v-model:input-value with the current text. |
@input-value-change | AutocompleteInputValueChangeDetails | Provides Ark input-change details. |
@update:model-value | string[] | Updates v-model with the selected option values. |
@value-change | AutocompleteValueChangeDetails | Provides details when selected option values change. |
@update:open | boolean | Updates v-model:open with the suggestion-surface state. |
@open-change | AutocompleteOpenChangeDetails | Provides 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
| Export | Description |
|---|---|
Autocomplete | Items-driven autocomplete with the compound parts attached as properties. |
AutocompleteRoot | Named root export for the same component. |
AutocompleteInputGroup | Input control with optional clear and suggestion triggers. |
AutocompleteContent | Portalled, positioned suggestion surface. |
AutocompleteList | Scrollable list with scoped item rendering. |
AutocompleteItem / AutocompleteItemText / AutocompleteItemIndicator | Selectable suggestion and its text and selected-state parts. |
AutocompleteEmpty | Empty state announced when no suggestion matches. |
AutocompleteGroup / AutocompleteGroupLabel / AutocompleteSeparator | Parts for grouped suggestion lists. |
AutocompleteLabel | Ark-connected accessible field label. |
createAutocompleteCollection | Kappa alias for Ark createListCollection. |
useAutocompleteCollection | Kappa alias for Ark useListCollection. |
AUTOCOMPLETE_SIZES | Readonly list of supported size names. |
Autocomplete* types | Public props, slots, event details, collection, filter, item, and positioning types. |