Autocomplete

Basic example

This example asks you to select your favorite fruit and provides suggestions as you type. You can enter any fruit, but the suggestions give you optional assistance for faster text entry.

Note that the suggested completion text (e.g. "anana" in "banana" if you type "b") is bolded in the list of suggestions, making it easy to scan the list for the completion you want.

To avoid overwhelming you with options, the autocomplete displays a maximum of five suggestions at a time. If you type "p", you won't initially see "pomegranate" listed, but if you type "po", you will.

value: [empty]

Custom rendering

It's often important to be able to display more than just text for each suggestion. In this case, since the suggestions are names of icons, it's useful to display the icon next to the name.

To give you this control but still make the completion text bold for easy scanning, we provide a component that handles the bolding for you. It's recommended to use this component whenever displaying suggestion text.

value: [empty]

Requiring a selection from the list

When you need one of the suggestions to be chosen (e.g. to guarantee only a validated address gets submitted), it's recommended to mark the autocomplete as required, enable auto-select, and enable selection on blur. You can also take full control of validation to show an error exactly when needed.

With auto-select, the top suggestion becomes active and auto-fills into the input as you type.

With selection on blur, if you leave the input, the active suggestion is automatically accepted and becomes the value of the input field. In most cases, especially for screen readers, this can facilitate easier address selection. In the rare case where the wrong suggestion is chosen based on the text you've entered, you have a chance to review and correct the selection before submitting the form.

value: [empty]

Search and navigation

This example allows you to search for the name of a component in this design system and navigate to its documentation page. With a site search, it is recommended to use auto-select and show an overlay on focus. It's often useful to hide the label, as shown here.

With auto-select, the top suggestion becomes active and auto-fills into the input as you type.

Showing an overlay on focus dims the rest of the page when the autocomplete is open. This is most appropriate when the autocomplete is prominently placed in a sticky bar at the top of the page, and serves to minimize distractions so the user can focus on selecting the right option.

Limited width

On mobile touch devices, interacting with the autocomplete opens a fullscreen takeover to ensure the full list of suggestions can be seen and interacted with. On desktop, the autocomplete may appear with its width limited by the page layout. In this case, the suggestions pane will expand in width as necessary to show the full list of suggestions. Try searching for "solar" or "heat pump".

value: [empty]

Error state

Message

value: [empty]

Disabled state

EsAutocomplete props

Required

Optional

EsAutocomplete events

EsAutocomplete slots