--- title: Autocomplete 自动补全 --- --- title: Autocomplete lang: en-US --- # Autocomplete 自动补全 Get some recommended tips based on the current input. ## Basic Usage Autocomplete component provides input suggestions. :::example The `fetch-suggestions` attribute is a method that return suggested inputs. In this example, `querySearch(queryString, cb)` return suggestions to Autocomplete via `cb(data)` when suggestions are ready. autocomplete/autocomplete ::: ## Custom template Customize how suggestions are displayed. :::example Use `scoped slot` to customize suggestion items. In the scope, you can access the suggestion object via the `item` key. autocomplete/autocomplete-template ::: ## Remote search Search data from server-side. :::example autocomplete/remote-search ::: ## Custom Loading ^(2.5.0) Override loading content. :::example autocomplete/custom-loading ::: ## Custom Header & Footer ^(2.10.6) You can customize both the header and footer of the dropdown using slots :::example Use slot to customize the content. autocomplete/custom-header-footer ::: ## API ### Attributes | Name | Description | Type | Default | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------ | | model-value / v-model | binding value | ^[string] | — | | placeholder | the placeholder of Autocomplete | ^[string] | — | | clearable | whether to show clear button | ^[boolean] | false | | disabled | whether Autocomplete is disabled | ^[boolean] | false | | value-key | key name of the input suggestion object for display | ^[string] | value | | debounce | debounce delay when typing, in milliseconds | ^[number] | 300 | | placement | placement of the popup menu | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end'` | bottom-start | | fetch-suggestions | a method to fetch input suggestions. When suggestions are ready, invoke `callback(data:[])` to return them to Autocomplete | ^[array] / ^[Function]`(queryString: string, callback: callbackfn) => void` | — | | trigger-on-focus | whether show suggestions when input focus | ^[boolean] | true | | select-when-unmatched | whether to emit a `select` event on enter when there is no autocomplete match | ^[boolean] | false | | name | same as `name` in native input | ^[string] | — | | aria-label ^(a11y) ^(2.7.2) | native `aria-label` attribute | ^[string] | — | | hide-loading | whether to hide the loading icon in remote search | ^[boolean] | false | | popper-class | custom class name for autocomplete's dropdown | ^[string] / ^[object] | '' | | popper-style ^(2.11.4) | custom style for autocomplete's dropdown | ^[string] / ^[object] | — | | popper-options ^(2.14.0) | [popper.js](https://popper.js.org/docs/v2/) parameters | ^[object]refer to [popper.js](https://popper.js.org/docs/v2/) doc | {} | | show-arrow ^(2.14.0) | whether the dropdown has an arrow | ^[boolean] | true | | teleported | whether select dropdown is teleported to the body | ^[boolean] | true | | append-to ^(2.9.9) | which select dropdown appends to | ^[CSSSelector] / ^[HTMLElement] | — | | highlight-first-item | whether to highlight first item in remote search suggestions by default | ^[boolean] | false | | fit-input-width | whether the width of the dropdown is the same as the input | ^[boolean] | false | | popper-append-to-body ^(deprecated) | whether to append the dropdown to body. If the positioning of the dropdown is wrong, you can try to set this prop to false | ^[boolean] | false | | loop-navigation ^(2.11.4) | whether keyboard navigation loops from end to start | ^[boolean] | true | | [input props](/docs/component/input#attributes) | — | — | — | ### Events | Name | Description | Type | | ------ | --------------------------------------------------------------- | ------------------------------------------------ | | blur | triggers when Input blurs | ^[Function]`(event: FocusEvent) => void` | | focus | triggers when Input focuses | ^[Function]`(event: FocusEvent) => void` | | input | triggers when the Input value change | ^[Function]`(value: string \| number) => void` | | clear | triggers when the Input is cleared by clicking the clear button | ^[Function]`() => void` | | select | triggers when a suggestion is clicked | ^[Function]`(item: Record) => void` | | change | triggers when the icon inside Input value change | ^[Function]`(value: string \| number) => void` | ### Slots | Name | Description | Type | | ---------------- | ------------------------------------- | ---------------------------------------- | | default | custom content for input suggestions | ^[object]`{ item: Record }` | | header ^(2.10.6) | content at the top of the dropdown | - | | footer ^(2.10.6) | content at the bottom of the dropdown | - | | prefix | content as Input prefix | - | | suffix | content as Input suffix | - | | prepend | content to prepend before Input | - | | append | content to append after Input | - | | loading ^(2.5.0) | override loading content | - | ### Exposes | Name | Description | Type | | ---------------- | ------------------------------------------- | --------------------------------------------------- | | activated | if autocomplete activated | ^[object]`Ref` | | blur | blur the input element | ^[Function]`() => void` | | close | collapse suggestion list | ^[Function]`() => void` | | focus | focus the input element | ^[Function]`() => void` | | handleSelect | triggers when a suggestion is clicked | ^[Function]`(item: any) => Promise` | | handleKeyEnter | handle keyboard enter event | ^[Function]`() => Promise` | | highlightedIndex | the index of the currently highlighted item | ^[object]`Ref` | | highlight | highlight an item in a suggestion | ^[Function]`(itemIndex: number) => void` | | inputRef | el-input component instance | ^[object]`Ref` | | loading | remote search loading indicator | ^[object]`Ref` | | popperRef | el-tooltip component instance | ^[object]`Ref` | | suggestions | fetch suggestions result | ^[object]`Ref[]>` | | getData ^(2.8.4) | loading suggestion list | ^[Function]`(queryString: string) => Promise` |