Phi / Autocomplete

Preview

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

const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Cherry", value: "cherry" },
];
</script>

<template>
  <Autocomplete :items="fruits">
    <Autocomplete.InputGroup placeholder="Search fruits..." />
    <Autocomplete.Content>
      <Autocomplete.Empty>No fruit suggestions.</Autocomplete.Empty>
      <Autocomplete.List>
        <template #default="{ item }">
          <Autocomplete.Item :item="item">
            {{ item.label }}
          </Autocomplete.Item>
        </template>
      </Autocomplete.List>
    </Autocomplete.Content>
  </Autocomplete>
</template>

Import

import { Autocomplete } from "@dicehub/phi/components/autocomplete";

Usage

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

const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Cherry", value: "cherry" },
];
</script>

<template>
  <Autocomplete :items="fruits">
    <Autocomplete.InputGroup placeholder="Search fruits..." />
    <Autocomplete.Content>
      <Autocomplete.Empty>No fruit suggestions.</Autocomplete.Empty>
      <Autocomplete.List>
        <template #default="{ item }">
          <Autocomplete.Item :item="item">
            {{ item.label }}
          </Autocomplete.Item>
        </template>
      </Autocomplete.List>
    </Autocomplete.Content>
  </Autocomplete>
</template>

The compound API uses a scoped Vue slot for item rendering.

For the shortest default UI, pass items directly.

<Autocomplete
  :items="fruits"
  placeholder="Search fruits..."
  aria-label="Search fruits"
/>

When To Use

Use Autocomplete when suggestions are hints and the final input can be custom text. Use a stricter Select or Combobox when the value must come from a known option list.

Controlled

Control the typed value with v-model:input-value. Suggestions stay optional and do not create a separate selected-value state.

<Autocomplete
  v-model:input-value="inputValue"
  :items="fruits"
  clearable
  placeholder="Type a fruit..."
/>

With Field

Pass label and helper text when the control is part of a form.

Error State

Pass invalid to the root and pair the input with visible validation text.

Grouped

Use groupBy on the collection and render AutocompleteGroup sections from collection.group().

Sizes

Autocomplete and AutocompleteInputGroup support xs, sm, base, and lg.

Custom Filtering

Use filter for local matching rules. For async or server-backed suggestions, pass a custom collection and compose the advanced parts.

<Autocomplete
  :items="fruits"
  :filter="(item, inputValue) => item.label.startsWith(inputValue)"
  placeholder="Search fruits..."
/>

API

Autocomplete

Prop	Type	Default	Description
`items`	`unknown[]`	`[]`	Items used by the default autocomplete UI.
`itemToString`	`(item) => string`	`item.label ?? String(item)`	Maps an item to visible text and default filtering text.
`itemToValue`	`(item) => string`	`item.value ?? itemToString(item)`	Maps an item to the Ark option value.
`filter`	`false \| function`	`contains label`	Custom item filter. Pass false to show all items for the current query.
`showOnEmpty`	`boolean`	`false`	Shows suggestions before the user enters a query.
`placeholder`	`string`	`-`	Placeholder for the default input.
`label`	`string`	`-`	Optional label rendered above the default input.
`clearable`	`boolean`	`false`	Renders a clear trigger in the default input.
`size`	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	Default input height and text size.
`collection`	`AutocompleteListCollection<T>`	`-`	Advanced Ark list collection used when composing custom content.
`allowCustomValue`	`boolean`	`true`	Allows free-form input values that are not constrained to suggestions.
`closeOnSelect`	`boolean`	`true`	Closes the popup after a suggestion is selected.
`inputValue`	`string`	`-`	Controlled text input value.
`open`	`boolean`	`-`	Controlled popup state.
`openOnChange`	`boolean \| function`	`Ark default`	Controls whether input changes open the popup.
`positioning`	`object`	`{ placement: "bottom-start", gutter: 4 }`	Ark positioning options for the popup.
`invalid`	`boolean`	`false`	Marks the control invalid for styling and Ark state.

AutocompleteInputGroup

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	Input height and text size.
`placeholder`	`string`	`-`	Placeholder passed to the internal input.
`clearable`	`boolean`	`false`	Renders an Ark clear trigger inside the control.
`showTrigger`	`boolean`	`false`	Shows or hides the optional popup trigger button.

Exports

Export	Description
`Autocomplete`	Simple items-driven autocomplete, with advanced compound slots when custom content is needed.
`Autocomplete.InputGroup`	Styled input with optional clear and popup triggers.
`Autocomplete.Content`	Positioned suggestion popup surface.
`Autocomplete.List`	Scrollable suggestion list with scoped-slot item rendering.
`Autocomplete.Item`	Styled selectable suggestion.
`Autocomplete.Label`	Ark label wrapper for accessible field labeling.
`Autocomplete.Group / Autocomplete.GroupLabel`	Grouped suggestion sections.
`Autocomplete.Empty`	Empty state shown when the collection has no matches.
`createAutocompleteCollection`	Advanced Phi alias for Ark createListCollection.
`useAutocompleteCollection`	Advanced Phi alias for Ark useListCollection.