---
title: "Autocomplete"
description: "An input with suggestions that allows free-form text entry. Unlike Combobox, the value is the input text itself rather than a selected item."
canonical_url: "https://vinicunca.dev/akar/components/autocomplete"
---
# Autocomplete

> An input with suggestions that allows free-form text entry. Unlike Combobox, the value is the input text itself rather than a selected item.

`````vue [index.vue]
<script setup lang="ts">
import { AutocompleteAnchor, AutocompleteContent, AutocompleteEmpty, AutocompleteGroup, AutocompleteInput, AutocompleteItem, AutocompleteLabel, AutocompleteRoot, AutocompleteSeparator, AutocompleteTrigger, AutocompleteViewport } from 'akar'
import { ref } from 'vue'
import './styles.css'

const v = ref('')

const options = [
  { name: 'Fruit', children: [
    { name: 'Apple' },
    { name: 'Banana' },
    { name: 'Orange' },
    { name: 'Honeydew' },
    { name: 'Grapes' },
    { name: 'Watermelon' },
    { name: 'Cantaloupe' },
    { name: 'Pear' },
  ] },
  { name: 'Vegetable', children: [
    { name: 'Cabbage' },
    { name: 'Broccoli' },
    { name: 'Carrots' },
    { name: 'Lettuce' },
    { name: 'Spinach' },
    { name: 'Bok Choy' },
    { name: 'Cauliflower' },
    { name: 'Potatoes' },
  ] },
]
</script>

<template>
  <div class="akar-demo akar-demo-Autocomplete">
    <AutocompleteRoot
        v-model="v"
        class="AutocompleteRoot"
      >
        <AutocompleteAnchor class="AutocompleteAnchor">
          <AutocompleteInput
            class="AutocompleteInput"
            placeholder="Type or select an option..."
          />
          <AutocompleteTrigger>
            <PIcon
              name="i-lucide-chevron-down"
              class="AutocompleteIcon"
            />
          </AutocompleteTrigger>
        </AutocompleteAnchor>

        <AutocompleteContent class="AutocompleteContent">
          <AutocompleteViewport class="AutocompleteViewport">
            <AutocompleteEmpty class="AutocompleteEmpty" />

            <template
              v-for="(group, index) in options"
              :key="group.name"
            >
              <AutocompleteGroup>
                <AutocompleteSeparator
                  v-if="index !== 0"
                  class="AutocompleteSeparator"
                />

                <AutocompleteLabel class="AutocompleteLabel">
                  {{ group.name }}
                </AutocompleteLabel>

                <AutocompleteItem
                  v-for="option in group.children"
                  :key="option.name"
                  :value="option.name"
                  class="AutocompleteItem"
                >
                  <span>
                    {{ option.name }}
                  </span>
                </AutocompleteItem>
              </AutocompleteGroup>
            </template>
          </AutocompleteViewport>
        </AutocompleteContent>
      </AutocompleteRoot>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/mauve.css';
@import '../_colors/grass.css';

@scope (.akar-demo-Autocomplete) {
/* reset */
button, input {
  all: unset;
}

.AutocompleteRoot {
  position: relative;
}

.AutocompleteAnchor {
  display: inline-flex;
  align-items: center;
  justify-content: space-between;
  font-size: 13px;
  line-height: 1;
  height: 35px;
  padding: 0 15px;
  gap: 5px;
  background-color: white;
  color: var(--grass-11);
  border-radius: 4px;
  box-shadow: 0 2px 10px var(--black-a7);
}
.AutocompleteAnchor:hover {
  background-color: var(--mauve-3);
}

.AutocompleteInput {    
  height: 100%;
  background-color: transparent;
  color: var(--grass-11); 
}
.AutocompleteInput[data-placeholder] {
  color: var(--grass-9);
}

.AutocompleteIcon {
  width: 16px;
  height: 16px;
  color: var(--grass-11);
}

.AutocompleteContent {
  z-index: 10;
  width: 100%;
  position: absolute;
  overflow: hidden;
  background-color: white;
  border-radius: 6px;
  margin-top: 8px;
  box-shadow: 0px 10px 38px -10px rgb(22 23 24 / 35%), 0px 10px 20px -15px rgb(22 23 24 / 20%);
}

.AutocompleteViewport {
  padding: 5px;
}

.AutocompleteEmpty {
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  text-align: center;
  font-size: 0.75rem;
  line-height: 1rem;
  font-weight: 500; 
  color: var(--mauve-11);
}

.AutocompleteItem {
  font-size: 13px;
  line-height: 1;
  color: var(--grass-11);
  border-radius: 3px;
  display: flex;
  align-items: center;
  height: 25px;
  padding: 0 35px 0 25px;
  position: relative;
  user-select: none;
}
.AutocompleteItem[data-disabled] {
  color: var(--mauve-8);
  pointer-events: none;
}
.AutocompleteItem[data-highlighted] {
  outline: none;
  background-color: var(--grass-9);
  color: var(--grass-1);
}

.AutocompleteLabel {
  padding: 0 25px;
  font-size: 12px;
  line-height: 25px;
  color: var(--mauve-11);
}

.AutocompleteSeparator {
  height: 1px;
  background-color: var(--grass-6);
  margin: 5px;
}
}
```

## Features

- Can be controlled or uncontrolled.
- Offers 2 positioning modes.
- Supports items, labels, groups of items.
- Focus is fully managed.
- Full keyboard navigation.
- Supports custom placeholder.
- Supports Right to Left direction.
- Free-form text input — value is the typed text, not a selection.

## Installation

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<script setup lang="ts">
import {
  AutocompleteAnchor,
  AutocompleteArrow,
  AutocompleteCancel,
  AutocompleteContent,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteLabel,
  AutocompletePortal,
  AutocompleteRoot,
  AutocompleteSeparator,
  AutocompleteTrigger,
  AutocompleteViewport,
} from 'akar';
</script>

<template>
  <AutocompleteRoot>
    <AutocompleteAnchor>
      <AutocompleteInput />
      <AutocompleteTrigger />
      <AutocompleteCancel />
    </AutocompleteAnchor>

    <AutocompletePortal>
      <AutocompleteContent>
        <AutocompleteViewport>
          <AutocompleteEmpty />

          <AutocompleteItem />

          <AutocompleteSeparator />

          <AutocompleteGroup>
            <AutocompleteLabel />
            <AutocompleteItem />
          </AutocompleteGroup>
        </AutocompleteViewport>

        <AutocompleteArrow />
      </AutocompleteContent>
    </AutocompletePortal>
  </AutocompleteRoot>
</template>
```

## Autocomplete vs. Combobox

The Autocomplete component is similar to the [Combobox](https://vinicunca.dev/akar/components/combobox) but with a key difference:

|  | Autocomplete | Combobox |
| --- | --- | --- |
| **`modelValue`** | The input text (`string`) | The selected item (`AcceptableValue`) |
| **Free-form text** | Yes — any text is valid | No — must select from the list |
| **`multiple`** | Not supported | Supported |
| **Input on blur** | Retains typed text by default | Resets to selected value by default |
| **Item selection** | Fills the input with the item's text value | Sets `modelValue` to the item's value |

Use **Autocomplete** when the user should be able to type anything with optional suggestions. Use **Combobox** when the user must pick from a predefined set of options.

## API Reference

### Root

Contains all the parts of an Autocomplete.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `defaultOpen` |  | `boolean` | The open state of the autocomplete when it is initially rendered. Use when you do not need to control its open state. |
| `defaultValue` |  | `string` | The value of the autocomplete when initially rendered. Use when you do not need to control the state. |
| `dir` |  | `"ltr" \| "rtl"` | The reading direction of the autocomplete when applicable. |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with autocomplete |
| `highlightOnHover` | `true` | `boolean` | When `true`, hover over item will trigger highlight |
| `ignoreFilter` |  | `boolean` | When `true`, disable the default filters |
| `modelValue` |  | `string` | The controlled value of the Autocomplete (the input text). Can be bound with `v-model`. |
| `name` |  | `string` | The name of the field. Submitted with its owning form as part of a name/value pair. |
| `open` |  | `boolean` | The controlled open state of the Autocomplete. Can be bound with `v-model:open`. |
| `openOnClick` | `false` | `boolean` | Whether to open the autocomplete when the input is clicked |
| `openOnFocus` | `false` | `boolean` | Whether to open the autocomplete when the input is focused |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `resetSearchTermOnBlur` | `false` | `boolean` | Whether to reset the searchTerm when the Autocomplete input blurred |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `highlight` | `payload: { ref: HTMLElement; value: string; }` | Event handler when highlighted element changes. |
| `update:modelValue` | `value: string` | Event handler called when the value changes. |
| `update:open` | `value: boolean` | Event handler called when the open state of the autocomplete changes. |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `open` | `boolean` | Current open state |
| `modelValue` | `string` | Current active value |

[AutocompleteRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Autocomplete/AutocompleteRoot.vue)

### Anchor

Used as an anchor if you set `AutocompleteContent`'s position to `popper`.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `reference` |  | `ReferenceElement` | The reference (or anchor) element that is being referred to for positioning.<br><br>If not provided will use the current component as anchor. |

[ComboboxAnchor.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxAnchor.vue)

### Input

The input component to search through the autocomplete items. Typing updates the `modelValue` directly.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"input"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `autoFocus` |  | `boolean` | Focus on element when mounted. |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with item |
| `modelValue` |  | `string` | The controlled value of the filter. Can be binded with v-model. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `string` |  |

[AutocompleteInput.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Autocomplete/AutocompleteInput.vue)

### Trigger

The button that toggles the Autocomplete Content.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with item |

[ComboboxTrigger.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxTrigger.vue)

| Data attribute | Value |
| --- | --- |
| `[data-state]` | "open" \\| "closed" |
| `[data-disabled]` | Present when disabled |

### Cancel

The button that clears the input text and resets the value.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ComboboxCancel.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxCancel.vue)

### Empty

Shown when none of the items match the query.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ComboboxEmpty.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxEmpty.vue)

### Portal

When used, portals the content part into the `body`.

You need to set `position="popper"` for `AutocompleteContent` to make sure the position was automatically computed similar to `Popover` or `DropdownMenu`.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `defer` |  | `boolean` | Defer the resolving of a Teleport target until other parts of the<br>application have mounted (requires Vue 3.5.0+)<br><br>[reference](https://vuejs.org/guide/built-ins/teleport.html#deferred-teleport) |
| `disabled` |  | `boolean` | Disable teleport and render the component inline<br><br>[reference](https://vuejs.org/guide/built-ins/teleport.html#disabling-teleport) |
| `forceMount` |  | `boolean` | Used to force mounting when more control is needed. Useful when<br>controlling animation with Vue animation libraries. |
| `to` |  | `string \| HTMLElement` | Vue native teleport component prop `:to`<br><br>[reference](https://vuejs.org/guide/built-ins/teleport.html#basic-usage) |

[ComboboxPortal.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxPortal.vue)

### Content

The component that pops out when the autocomplete is open.

> [!NOTE]
> 
> Defer mounting with `forceMount` / [`Presence`](https://vinicunca.dev/akar/utilities/presence). See the [animation guide](https://vinicunca.dev/akar/guides/animation).

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `align` | `"center"` | `"start" \| "center" \| "end"` | The preferred alignment against the trigger.<br>May change when collisions occur. |
| `alignFlip` | `true` | `boolean` | Flip alignment when colliding with boundary.<br>May only occur when `prioritizePosition` is true. |
| `alignOffset` | `0` | `number` | An offset in pixels from the `start` or `end` alignment options. |
| `arrowPadding` | `0` | `number` | The padding between the arrow and the edges of the content.<br>If your content has border-radius, this will prevent it from<br>overflowing the corners. |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `avoidCollisions` | `true` | `boolean` | When `true`, overrides the side and align preferences<br>to prevent collisions with boundary edges. |
| `bodyLock` |  | `boolean` | The document.body will be lock, and scrolling will be disabled. |
| `collisionBoundary` | `[]` | `Element \| (Element \| null)[] \| null` | The element used as the collision boundary. By default<br>this is the viewport, though you can provide additional<br>element(s) to be included in this check. |
| `collisionPadding` | `0` | `number \| Partial<Record<"top" \| "right" \| "bottom" \| "left", number>>` | The distance in pixels from the boundary edges where collision<br>detection should occur. Accepts a number (same for all sides),<br>or a partial padding object, for example: { top: 20, left: 20 }. |
| `dir` |  | `"ltr" \| "rtl"` | The reading direction of the popper content when applicable.<br><br>If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. |
| `disableOutsidePointerEvents` |  | `boolean` | When `true`, hover/focus/click interactions will be disabled on elements outside<br>the `DismissableLayer`. Users will need to click twice on outside elements to<br>interact with them: once to close the `DismissableLayer`, and again to trigger the element. |
| `disableUpdateOnLayoutShift` | `false` | `boolean` | Whether to disable the update position for the content when the layout shifted. |
| `forceMount` |  | `boolean` | Used to force mounting when more control is needed. Useful when<br>controlling animation with Vue animation libraries. |
| `hideShiftedArrow` | `true` | `boolean` | When `true`, hides the arrow when it cannot be centered<br>to the reference element. |
| `hideWhenDetached` | `false` | `boolean` | Whether to hide the content when the trigger becomes fully occluded. |
| `hideWhenEmpty` | `false` | `boolean` | When `true`, hides the content when there are no items matching the filter. |
| `memoDependencies` |  | `unknown[]` | Reactive dependencies that should invalidate the memoized content subtree. |
| `position` |  | `"inline" \| "popper"` | The positioning mode to use,<br><br>`inline` is the default and you can control the position using CSS.<br><br>`popper` positions content in the same way as our other primitives, for example `Popover` or `DropdownMenu`. |
| `positionStrategy` |  | `"fixed" \| "absolute"` | The type of CSS position property to use. |
| `present` |  | `boolean` | Whether this kept-mounted content is currently visible. |
| `prioritizePosition` | `false` | `boolean` | Force content to be position within the viewport.<br><br>Might overlap the reference element, which may not be desired. |
| `reference` |  | `ReferenceElement` | The custom element or virtual element that will be set as the reference<br>to position the floating element.<br><br>If provided, it will replace the default anchor element. |
| `side` | `"bottom"` | `"top" \| "right" \| "bottom" \| "left"` | The preferred side of the trigger to render against when open.<br>Will be reversed when collisions occur and avoidCollisions<br>is enabled. |
| `sideFlip` | `true` | `boolean` | Flip to the opposite side when colliding with boundary. |
| `sideOffset` | `0` | `number` | The distance in pixels from the trigger. |
| `sticky` | `"partial"` | `"partial" \| "always"` | The sticky behavior on the align axis. `partial` will keep the<br>content in the boundary as long as the trigger is at least partially<br>in the boundary whilst "always" will keep the content in the boundary<br>regardless. |
| `updatePositionStrategy` | `'optimized'` | `"always" \| "optimized"` | Strategy to update the position of the floating element on every animation frame. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `escapeKeyDown` | `event: KeyboardEvent` | Event handler called when the escape key is down.<br>Can be prevented. |
| `focusOutside` | `event: FocusOutsideEvent` | Event handler called when the focus moves outside of the `DismissableLayer`.<br>Can be prevented. |
| `interactOutside` | `event: PointerDownOutsideEvent \| FocusOutsideEvent` | Event handler called when an interaction happens outside the `DismissableLayer`.<br>Specifically, when a `pointerdown` event happens outside or focus moves outside of it.<br>Can be prevented. |
| `pointerDownOutside` | `event: PointerDownOutsideEvent` | Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`.<br>Can be prevented. |

[ComboboxContent.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxContent.vue)

| Data attribute | Value |
| --- | --- |
| `[data-state]` | "open" \\| "closed" |
| `[data-side]` | "left" \\| "right" \\| "bottom" \\| "top" |
| `[data-align]` | "start" \\| "end" \\| "center" |
| `[data-empty]` | Present when there are no items matching the filter |

| CSS variable | Description |
| --- | --- |
| `--akar-combobox-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets. Only present when `position="popper"`. |
| `--akar-combobox-content-available-width` | The remaining width between the trigger and the boundary edge. Only present when `position="popper"`. |
| `--akar-combobox-content-available-height` | The remaining height between the trigger and the boundary edge. Only present when `position="popper"`. |
| `--akar-combobox-trigger-width` | The width of the trigger. Only present when `position="popper"`. |
| `--akar-combobox-trigger-height` | The height of the trigger. Only present when `position="popper"`. |

### Viewport

The scrolling viewport that contains all of the items.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `nonce` |  | `string` | Will add `nonce` attribute to the style tag which can be used by Content Security Policy.<br><br>If omitted, inherits globally from `ConfigProvider`. |

[ComboboxViewport.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxViewport.vue)

### Item

The component that contains the autocomplete items. When selected, the item's string value fills the input.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with the item. |
| `textValue` |  | `string` | A string representation of the item contents.<br><br>If the children are not plain text, then the `textValue` prop must also be set to a plain text representation, which will be used for autocomplete in the ComboBox. |
| `value*` |  | `T` | The value given as data when submitted with a `name`. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `select` | `event: SelectEvent<T>` | Event handler called when the selecting item.<br><br>It can be prevented by calling `event.preventDefault`. |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `selected` | `boolean` | Whether the item is currently selected |

[ComboboxItem.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxItem.vue)

| Data attribute | Value |
| --- | --- |
| `[data-state]` | "checked" \\| "unchecked" |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |

### Group

Used to group multiple items. Use in conjunction with `AutocompleteLabel` to ensure good accessibility via automatic labelling.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ComboboxGroup.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxGroup.vue)

### Label

Used to render the label of a group. It won't be focusable using arrow keys.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `for` |  | `string` |  |

[ComboboxLabel.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxLabel.vue)

### Separator

Used to visually separate items in the Autocomplete.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"div"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |

[ComboboxSeparator.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxSeparator.vue)

### Arrow

An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the `AutocompleteContent`. Must be rendered inside `AutocompleteContent`. Only available when `position` is set to `popper`.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"svg"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](/akar/guides/composition) guide for more details. |
| `height` | `5` | `number` | The height of the arrow in pixels. |
| `rounded` | `false` | `boolean` | When `true`, render the rounded version of arrow. Do not work with `as`/`asChild` |
| `width` | `10` | `number` | The width of the arrow in pixels. |

[ComboboxArrow.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxArrow.vue)

### Virtualizer

Virtual container to achieve list virtualization.

See the [virtualization guide](https://vinicunca.dev/akar/guides/virtualization.md) for more general info on virtualization.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `estimateSize` |  | `number \| ((index: number) => number)` | Estimated size (in px) of each item |
| `options*` |  | `T` | List of items |
| `overscan` |  | `number` | Number of items rendered outside the visible area |
| `textContent` |  | `((option: T) => string)` | Text content for each item to achieve type-ahead feature |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `option` | `T` |  |
| `virtualizer` | `Virtualizer<HTMLElement, Element>` |  |
| `virtualItem` | `VirtualItem` |  |

[ComboboxVirtualizer.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Combobox/ComboboxVirtualizer.vue)

## Examples

### Basic usage

The `modelValue` is a string that reflects whatever the user types. Selecting an item fills the input with that item's text.

```vue
<script setup lang="ts">
import { AutocompleteContent, AutocompleteInput, AutocompleteItem, AutocompletePortal, AutocompleteRoot } from 'akar';
import { ref } from 'vue';

const searchText = ref('');
const fruits = ['Apple', 'Banana', 'Orange', 'Grapes', 'Pineapple'];
</script>

<template>
  <AutocompleteRoot v-model="searchText">
    <AutocompleteInput placeholder="Type a fruit..." />
    <AutocompletePortal>
      <AutocompleteContent>
        <AutocompleteItem
          v-for="fruit in fruits"
          :key="fruit"
          :value="fruit"
        >
          {{ fruit }}
        </AutocompleteItem>
      </AutocompleteContent>
    </AutocompletePortal>
  </AutocompleteRoot>
</template>
```

### Hide menu when empty

Use the `hideWhenEmpty` prop on `AutocompleteContent` to hide the menu when no items match the filter.

```vue
<template>
  <AutocompleteRoot v-model="searchText">
    <AutocompleteInput placeholder="Type a fruit..." />
    <AutocompletePortal>
      <AutocompleteContent hide-when-empty>
        <AutocompleteItem
          v-for="fruit in fruits"
          :key="fruit"
          :value="fruit"
        >
          {{ fruit }}
        </AutocompleteItem>
      </AutocompleteContent>
    </AutocompletePortal>
  </AutocompleteRoot>
</template>
```

### With form submission

The Autocomplete value is submitted as a regular text field in forms.

```vue
<script setup lang="ts">
import { AutocompleteContent, AutocompleteInput, AutocompleteItem, AutocompletePortal, AutocompleteRoot } from 'akar';
import { ref } from 'vue';

const query = ref('');
const cities = ['New York', 'Los Angeles', 'Chicago', 'Houston', 'Phoenix'];
</script>

<template>
  <form>
    <AutocompleteRoot
      v-model="query"
      name="city"
    >
      <AutocompleteInput placeholder="Enter a city..." />
      <AutocompletePortal>
        <AutocompleteContent>
          <AutocompleteItem
            v-for="city in cities"
            :key="city"
            :value="city"
          >
            {{ city }}
          </AutocompleteItem>
        </AutocompleteContent>
      </AutocompletePortal>
    </AutocompleteRoot>
  </form>
</template>
```

## Accessibility

Adheres to the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox).

### Keyboard Interactions

| Key | Description |
| --- | --- |

---

- [ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/combobox)
- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Autocomplete)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.