Components
Autocomplete
An input that suggests values as you type while still accepting any text.
Source code
Click to see the source code for this component on GitHub. Feel free to copy it and adjust it for your own use.
Installation
To use the autocomplete inside a Vee-Validate form, see VeeAutocomplete.
Autocomplete vs. Combobox
The autocomplete is built on Reka UI's Autocomplete primitive. It looks like UiCombobox but behaves differently:
| Autocomplete | Combobox | |
|---|---|---|
v-model | The text in the input (string) | The selected item(s) |
| Free-form text | Yes, any text is a valid value | No, the value must be one of the items |
| Selecting an item | Fills the input with the item's text | Sets the model to the item's value |
| On blur | Keeps the typed text | Resets the input to the selection |
multiple / object values | Not supported | Supported |
Use the autocomplete when suggestions are only a convenience (search boxes, emails, addresses, tags, job titles). Use a combobox when the user has to pick from a fixed list, or when you need objects or multiple selection.
Usage
Basic
The value of the autocomplete is the text in the input. Selecting a suggestion fills the input with that suggestion, but any other text is a perfectly valid value too. Suggestions are filtered as the user types.
Value: (empty)
Open on focus or click
By default the suggestions open once the user starts typing or presses the arrow keys. Use open-on-focus or open-on-click to open them as soon as the input is focused or clicked.
Clearable
Use UiAutocompleteCancel to render a button that clears the input.
Groups
Use UiAutocompleteGroup and UiAutocompleteLabel to organise the suggestions. Visible groups are divided by a line automatically, and groups that do not match the search are hidden along with their divider. Individual items can be disabled. UiAutocompleteSeparator is still available for manual dividers outside of groups.
Custom item content
Items accept any content, such as flags, avatars or descriptions.
Search
Set hide-when-empty on UiAutocompleteContent to keep the popup hidden until at least one suggestion matches. This makes the autocomplete behave like a search box with suggestions.
Email suggestions
Suggestions do not have to come from a static list. Here they are derived from what the user typed. Because the suggestions already match the input, built-in filtering is turned off with ignore-filter.
Type a name followed by @ to see domain suggestions.
Async
Fetch suggestions from your API as the user types. Use ignore-filter so the results returned from the server are not filtered a second time on the client.
Form
Pass a name to include the typed text when the surrounding <form> is submitted.
Disabled
Set disabled on the root to prevent interaction.
Props
Autocomplete
| Prop | Type | Default | Description |
|---|---|---|---|
v-model | string | "" | The text in the input. |
default-value | string | Initial text when uncontrolled. | |
v-model:open | boolean | Controls whether the suggestions are open. | |
default-open | boolean | Initial open state when uncontrolled. | |
open-on-focus | boolean | false | Open the suggestions when the input is focused. |
open-on-click | boolean | false | Open the suggestions when the input is clicked. |
ignore-filter | boolean | false | Disable the built-in filtering. Use it when you filter the items yourself, for example with data from an API. |
reset-search-term-on-blur | boolean | false | Reset the search term to the current value when the input loses focus. |
highlight-on-hover | boolean | true | Highlight items on hover. |
loop | boolean | false | Wrap keyboard navigation from the last item to the first and vice versa. |
name | string | Name used when the input is part of a native form. | |
required | boolean | Marks the field as required. | |
disabled | boolean | Prevents interaction. | |
dir | "ltr" | "rtl" | Reading direction. |
The root emits update:modelValue, update:open and highlight.
AutocompleteContent
Accepts all of the Reka UI popper content props. The ones used most often are:
| Prop | Type | Default | Description |
|---|---|---|---|
hide-when-empty | boolean | false | Hide the popup while no item matches. |
side | "top" | "right" | "bottom" | "left" | "bottom" | Preferred side of the input. |
side-offset | number | 8 | Distance in pixels from the input. |
position | "inline" | "popper" | "popper" | Positioning strategy. |
AutocompleteItem
| Prop | Type | Description |
|---|---|---|
value | string | The text that fills the input when the item is selected. Also used for filtering. |
disabled | boolean | Prevents the item from being selected. |
Accessibility
The input has the combobox role with aria-autocomplete="list", and the suggestions are exposed as a listbox. Focus stays in the input while you move through the suggestions.
| Key | Description |
|---|---|
ArrowDown / ArrowUp | Opens the suggestions, then moves the highlight. |
Enter | Fills the input with the highlighted suggestion. |
Esc | Closes the suggestions and keeps focus in the input. |
Tab | Moves focus away. The typed text is kept. |