Learn how to show different types of results in one autocomplete.
While autocompletes with suggested searches is a ubiquitous search experience, rich multi-category autocompletes are becoming more and more popular.
For example, if you search for something in your email inbox, your results could contain not just email threads, but also contacts, attachments, and more. Ecommerce stores often show suggested searches, products, blog posts, brands, and categories all in one autocomplete.
It's best to display different results types in different sections. This implicitly gives users a better understanding of what the items are, and what will happen if they select an item.
The Autocomplete library lets you mix different item types in one autocomplete and customize their display. To do so you need to return multiple sources in the
getSources option. This tutorial outlines how to combine static predefined items, recent searches] and Query Suggestions in one autocomplete.
Though it's not necessary, it uses plugins for each source. Instead, you could add different sources directly in
getSources. However, it's recommend to encapsulate source logic in a plugin since this makes it modular, reusable, and sharable.
This tutorial assumes that you have:
- a populated Query Suggestions index
- existing markup containing an input element where you want to implement the autocomplete dropdown
First, begin with some boilerplate for the autocomplete implementation. Create a file called
index.js in your
src directory, and add the boilerplate below:
This boilerplate assumes you want to insert the autocomplete into a DOM element with
autocomplete as an
id. You should change the
container to match your markup. Setting
true ensures that the dropdown appears as soon as a user focuses the input.
plugins is an empty array, but you'll learn how to create and add plugins for predefined items, recent searches, and Query Suggestions next.
A popular search pattern for autocomplete menus shows predefined search terms as soon as a user clicks on the search bar and before they begin typing anything. This UX provides a guided experience and exposes users to helpful resources or other content you want them to see.
This tutorial describes how to create a plugin to show static, predefined items. In particular, it exposes helpful links the user may want to refer to.
Begin by creating a
predefinedItemsPlugin.js file in your
src directory, with the following code:
predefinedItemsPlugin has a similar signature as any other autocomplete implementation: it uses the
getSources option to return an array of items to display. Each object in the array defines where to get items using
getItems. An Autocomplete plugin is an object that implements the
AutocompletePlugin interface. To learn more, check out the documentation on building your own plugin.
In this example,
getItems returns a filtered array of
predefinedItems. The code filters the array to return items that match the query, if it exists. If it doesn't, it returns the entire array. You can return whatever predefined items you like and format them accordingly. For example, suppose you want to show trending search items instead of helpful links. Then, you can use
getItems to retrieve them from another source, including an asynchronous API.
getItemUrl function defines how to get the URL of an item. In this case, since it's an attribute on each object in the
predefinedItems array, you can simply return the attribute. You can use
getItemUrl to add keyboard navigation to the autocomplete menu. Users can scroll through items in the autocomplete menu with the arrow up and down keys. When they hit Enter on one of the
predefinedItems (or any source that includes
getItemUrl), it opens the URL retrieved from
All that's left is to import the newly created
predefinedItemsPlugin and add it to
index.js. Once you've done that, the file should look like this:
Now, as soon as a user clicks on the search bar, these predefined items appear. Once they begin typing, only predefined items that contain the query remain.
Use the out-of-the-box
createLocalStorageRecentSearchesPlugin function to create a recent searches plugin:
key can be any string and is required to differentiate search histories if you have multiple autocompletes on one page. The
limit defines the maximum number of recent searches to display.
If you don't have a Query Suggestions index yet, follow the guide on creating a Query Suggestions index. You can also use the demo application credentials and index name provided in this tutorial.
Use the out-of-the-box
createQuerySuggestionsPlugin function to create a Query Suggestions plugin. It requires an Algolia search client initialized with an Algolia application ID and API key and an
indexName is the name of your Query Suggestions index.
When instantiating your Query Suggestions plugin, you can optionally pass a
getSearchParams function to apply Algolia query parameters to the suggestions returned from the plugin. This is particularly useful if you need to coordinate your Query Suggestions with other sections displayed in the autocomplete, like recent searches.
For example, if you'd like to show a combined total of ten search terms (recent searches plus Query Suggestions), you can indicate this:
This shows up to five recent searches (set by the
limit parameter) and up to ten total search terms. If there's only one recent search in local storage, the autocomplete displays nine Query Suggestions, assuming that there are nine relevant suggestions.
When using sources other than just recent and suggested searches, it's best to label the different result types with
headers. For the
createQuerySuggestionsPlugin plugins, you can use the
transformSource option to do this.
All that's left to do is add all of your plugins to your autocomplete instance:
This creates a basic multi-source autocomplete. Try it out below:
This tutorial combined three sources in one autocomplete. Depending on your use case, you might want to add more or different ones than the ones included here. Regardless of what you use for your sections, the method is the same: provide a different a source for each.
You may also choose to style your multi-source autocomplete differently by creating a horizontal layout or further differentiating how to display each source type.