Menu
Documentation
v4.0.0-beta.4

Autocomplete

<BaseAutocomplete /> · An interactive search box.

View SourceOpen Issue
vue
<template>
  <BaseAutocomplete
    v-model="fields.first"
    placeholder="Ex: nuxt"
  >
    <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
      {{ item }}
    </BaseAutocompleteItem>
  </BaseAutocomplete>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

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

Anatomy

This component has a default slot that can be used to add items, labels, groups of items, and separators. You can customize the autocomplete's visual style by using the available props.

vue
<template>
  <BaseAutocomplete>
    <BaseAutocompleteItem>
      <!-- Your content here -->
    </BaseAutocompleteItem>
  </BaseAutocomplete>
</template>

API Reference

This component has props that you can use to modify its visual style and behavior.

Autocomplete

Model Type
model-value
AcceptableValue | AcceptableValue[]

The controlled value of the listbox. Can be binded with with `v-model`.

Prop Type
query
default:-
string

The controlled value of the filter.

items
default:[]
BaseAutocompleteItemProps<AcceptableValue>[]

Items to display in the autocomplete list instead of slots.

variant
default:"default"
"default" | "muted" | "none"

The variant of the autocomplete

rounded
default:"md"
"none" | "sm" | "md" | "lg" | "full"

The radius of the component.

size
default:"md"
"sm" | "md" | "lg" | "xl"

The size of the autocomplete component.

clearable
default:-
boolean

Display the clear button to reset the query.

preset
default:"popper"
"inline" | "popper"

Bindings presets

bindings
default:{}
{ anchor?: ComboboxAnchorProps; trigger?: ComboboxTriggerProps; portal?: ComboboxPortalProps; content?: ComboboxContentProps; viewport?: ComboboxViewportProps; empty?: ComboboxEmptyProps; }

Optional bindings to pass to the inner components.

classes
default:{}
{ root?: string | string[]; anchor?: string | string[]; cancel?: string | string[]; trigger?: string | string[]; content?: string | string[]; viewport?: string | ... 1 more ...; empty?: string | ... 1 more ...; }

Optional classes to pass to the inner components.

open
default:-
boolean

The controlled open state of the Combobox. Can be binded with with `v-model:open`.

default-open
default:-
boolean

The open state of the combobox when it is initially rendered. Use when you do not need to control its open state.

reset-search-term-on-blur
default:-
boolean

Whether to reset the searchTerm when the Combobox input blurred

reset-search-term-on-select
default:-
boolean

Whether to reset the searchTerm when the Combobox value is selected

ignore-filter
default:-
boolean

When `true`, disable the default filters

default-value
default:-
AcceptableValue | AcceptableValue[]

The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox

multiple
default:-
boolean

Whether multiple options can be selected or not.

dir
default:-
Direction

The reading direction of the listbox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.

disabled
default:-
boolean

When `true`, prevents the user from interacting with listbox

highlight-on-hover
default:-
boolean

When `true`, hover over item will trigger highlight

by
default:-
string | ((a: AcceptableValue, b: AcceptableValue) => boolean)

Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.

as-child
default:-
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior. Read our [Composition](https://www.reka-ui.com/docs/guides/composition) guide for more details.

as
default:-
AsTag | Component

The element or component this component should render as. Can be overwritten by `asChild`.

name
default:-
string

The name of the field. Submitted with its owning form as part of a name/value pair.

required
default:-
boolean

When `true`, indicates that the user must set the value before the owning form can be submitted.

Event Emitted Value Type
update:query
[value: string]
highlight
[payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]
update:open
[value: boolean]
Slot Type
#default
any
#empty
{ open: boolean; query: string; modelValue: AcceptableValue | AcceptableValue[]; }
#content-start
{ open: boolean; query: string; modelValue: AcceptableValue | AcceptableValue[]; }
#content-end
{ open: boolean; query: string; modelValue: AcceptableValue | AcceptableValue[]; }
#viewport-start
{ open: boolean; query: string; modelValue: AcceptableValue | AcceptableValue[]; }
#viewport-end
{ open: boolean; query: string; modelValue: AcceptableValue | AcceptableValue[]; }

Group

Prop Type
as-child
default:-
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior. Read our [Composition](https://www.reka-ui.com/docs/guides/composition) guide for more details.

as
default:-
AsTag | Component

The element or component this component should render as. Can be overwritten by `asChild`.

Slot Type
#default
any

Item

Prop Type
text-value
default:-
string

A string representation of the item contents. 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
default:-
AcceptableValue

The value given as data when submitted with a `name`.

disabled
default:-
boolean

When `true`, prevents the user from interacting with the item.

as-child
default:-
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior. Read our [Composition](https://www.reka-ui.com/docs/guides/composition) guide for more details.

as
default:-
AsTag | Component

The element or component this component should render as. Can be overwritten by `asChild`.

Event Emitted Value Type
select
[event: ListboxItemSelectEvent<AcceptableValue>]
Slot Type
#default
any

Label

Prop Type
label
default:""
string

The label to display for the Autocomplete.

for
default:-
string
as-child
default:-
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior. Read our [Composition](https://www.reka-ui.com/docs/guides/composition) guide for more details.

as
default:-
AsTag | Component

The element or component this component should render as. Can be overwritten by `asChild`.

Slot Type
#default
any

Separator

Prop Type
as-child
default:-
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior. Read our [Composition](https://www.reka-ui.com/docs/guides/composition) guide for more details.

as
default:-
AsTag | Component

The element or component this component should render as. Can be overwritten by `asChild`.

Customization

Your can override the component default CSS variables in your main.css file.

css
@theme {
  /* Default input variables */
  --color-input-default-border: var(--color-muted-300);
  --color-input-default-bg: var(--color-white);
  --color-input-default-text: var(--color-muted-600);
  --color-input-default-placeholder: var(--color-muted-300);
  --color-input-default-button-bg: var(--color-muted-100);
  --color-input-default-button-bg-active: var(--color-muted-200);
  --color-input-default-button-text: var(--color-muted-700);

  /* Muted input variables */
  --color-input-muted-border: var(--color-muted-300);
  --color-input-muted-bg: var(--color-muted-50);
  --color-input-muted-text: var(--color-muted-600);
  --color-input-muted-placeholder: var(--color-muted-300);
  --color-input-muted-button-bg: var(--color-muted-200);
  --color-input-muted-button-bg-active: var(--color-muted-300);
  --color-input-muted-button-text: var(--color-muted-700);
}

Examples

Size

Use the size prop to change the size of the autocomplete.

vue
<template>
  <BaseAutocomplete
    v-model="fields.second"
    size="md"
    placeholder="Ex: nuxt"
  >
    <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
      {{ item }}
    </BaseAutocompleteItem>
  </BaseAutocomplete>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Variants

Use the variant prop to change the contrast of the autocomplete.

vue
<template>
  <BaseAutocomplete
    v-model="fields.second"
    variant="muted"
    placeholder="Ex: nuxt"
  >
    <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
      {{ item }}
    </BaseAutocompleteItem>
  </BaseAutocomplete>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Groups

Use the BaseAutocompleteGroup component to group items.

vue
<template>
  <BaseAutocomplete
    v-model="fields.first"
    rounded="md"
    placeholder="Ex: nuxt"
  >
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Frameworks
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
  </BaseAutocomplete>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]

const languages = [
  'JavaScript',
  'TypeScript',
  'Python',
  'Ruby',
  'Java',
  'C#',
  'PHP',
  'Go',
  'Rust',
  'Swift',
  'Kotlin',
  'Dart',
  'Scala',
  'Elixir',
  'Clojure',
]
</script>

Presets

Use the available presets to quickly change the autocomplete's visual style.

vue
<template>
  <BaseAutocomplete preset="popper" placeholder="popper">
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Frameworks
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
  </BaseAutocomplete>
  <BaseAutocomplete preset="inline" placeholder="Inline">
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Frameworks
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
    <BaseAutocompleteSeparator />
    <BaseAutocompleteGroup>
      <BaseAutocompleteLabel>
        Languages
      </BaseAutocompleteLabel>
      <BaseAutocompleteItem v-for="item in languages" :key="item" :value="item">
        {{ item }}
      </BaseAutocompleteItem>
    </BaseAutocompleteGroup>
  </BaseAutocomplete>
</template>

<script setup lang="ts">
const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]

const languages = [
  'JavaScript',
  'TypeScript',
  'Python',
  'Ruby',
  'Java',
  'C#',
  'PHP',
  'Go',
  'Rust',
  'Swift',
  'Kotlin',
  'Dart',
  'Scala',
  'Elixir',
  'Clojure',
]
</script>

Multiple string selection

Use the multiple prop to be able to select multiple items at once.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          v-model="multipleValue"
          rounded="md"
          placeholder="Ex: nuxt"
          multiple
        >
          <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
            {{ item }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const multipleValue = ref<string[]>(['Nuxt', 'Vue.js'])
const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Multiple object selection

Use the multiple prop to be able to select multiple items at once.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          v-model="multiplePerson"
          by="id"
          rounded="md"
          placeholder="Search..."
          multiple
        >
          <BaseAutocompleteItem v-for="item in persons" :key="item.id" :value="item">
            {{ item.name }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const persons = [
  {
    id: 1,
    name: 'Clarissa Perez',
    text: 'Sales Manager',
    media: 'https://tairo.cssninja.io/img/avatars/19.svg',
  },
  {
    id: 2,
    name: 'Aaron Splatter',
    text: 'Project Manager',
    media: 'https://tairo.cssninja.io/img/avatars/16.svg',
  },
  {
    id: 3,
    disabled: true,
    name: 'Mike Miller',
    text: 'UI/UX Designer',
    media: 'https://tairo.cssninja.io/img/avatars/3.svg',
  },
  {
    id: 4,
    name: 'Benedict Kessler',
    text: 'Mobile Developer',
    media: 'https://tairo.cssninja.io/img/avatars/22.svg',
  },
  {
    id: 5,
    name: 'Maya Rosselini',
    text: 'Product Manager',
    media: 'https://tairo.cssninja.io/img/avatars/2.svg',
  },
]
const multiplePerson = ref([persons[1]!])
</script>

Clearable

Use the clearable prop to add a clear button to the autocomplete.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          v-model="fields.first"
          rounded="md"
          placeholder="Ex: nuxt"
          clearable
        >
          <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
            {{ item }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Error

Use the aria-invalid prop to indicate that the input has an error.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          v-model="fields.first"
          rounded="md"
          placeholder="Ex: nuxt"
          aria-invalid="true"
        >
          <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
            {{ item }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Disabled

Use the disabled prop to disable the autocomplete.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          v-model="fields.first"
          rounded="md"
          placeholder="Ex: nuxt"
          disabled
        >
          <BaseAutocompleteItem v-for="item in frameworks" :key="item" :value="item">
            {{ item }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const fields = reactive({
  first: '',
})

const frameworks = [
  'Nuxt',
  'Vue.js',
  'React.js',
  'Angular',
  'Alpine.js',
]
</script>

Slots

This component has multiple slots that you can use to customize how your items render and behave.

vue
<template>
  <div class="flex items-center justify-center px-4 pb-0 pt-4">
    <div class="w-full rounded-xl bg-muted-100 p-4 dark:bg-muted-900 md:p-6">
      <div class="max-w-xs">
        <BaseAutocomplete
          placeholder="Hide create prompt"
        >
          <template #empty>
            <BaseCard variant="muted">
              #empty
            </BaseCard>
          </template>
          <template #viewport-start="{ query }">
            <BaseCard variant="muted">
              #viewport-start { {{ query }} }
            </BaseCard>
          </template>
          <template #viewport-end>
            <BaseCard variant="muted">
              #viewport-end
            </BaseCard>
          </template>
          <template #content-start>
            <BaseCard>
              #content-start
            </BaseCard>
          </template>
          <template #content-end>
            <BaseCard>
              #content-end
            </BaseCard>
          </template>
          <BaseAutocompleteItem v-for="item in persons" :key="item.id" :value="item">
            {{ item.name }}
          </BaseAutocompleteItem>
        </BaseAutocomplete>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const persons = [
  {
    id: 1,
    name: 'Clarissa Perez',
    text: 'Sales Manager',
    media: 'https://tairo.cssninja.io/img/avatars/19.svg',
  },
  {
    id: 2,
    name: 'Aaron Splatter',
    text: 'Project Manager',
    media: 'https://tairo.cssninja.io/img/avatars/16.svg',
  },
  {
    id: 3,
    disabled: true,
    name: 'Mike Miller',
    text: 'UI/UX Designer',
    media: 'https://tairo.cssninja.io/img/avatars/3.svg',
  },
  {
    id: 4,
    name: 'Benedict Kessler',
    text: 'Mobile Developer',
    media: 'https://tairo.cssninja.io/img/avatars/22.svg',
  },
  {
    id: 5,
    name: 'Maya Rosselini',
    text: 'Product Manager',
    media: 'https://tairo.cssninja.io/img/avatars/2.svg',
  },
]
</script>

Accordion

Avatar