Autocomplete

Autocomplete is a ubiquitous part of most search experiences. Search providers like Google, ecommerce sites like Amazon, and messaging apps like Slack all offer autocomplete experiences on mobile and desktop.

Screenshot of a search box with 'laptop' entered, showing autocomplete suggestions and product listings for Apple MacBooks.

Algolia provides a full-featured solution to build autocomplete experiences with InstantSearch. The autocomplete widget lets you build an accessible, as-you-type autocomplete user interface that you can integrate anywhere on your site or app.

Open CodeSandbox

Run and edit the Autocomplete example in CodeSandbox.

Explore source code

Browse the source for the Autocomplete example on GitHub.

A common pattern in search is to implement a search box with an autocomplete as a first step of the search experience. Adding an autocomplete to a search page lets you enhance the search experience and create a richer, more contextual search. You can use the autocomplete widget in an existing or a new InstantSearch.js implementation to create this kind of experience.

Install InstantSearch.js

The autocomplete widget is part of InstantSearch.js. Install InstantSearch.js and the Algolia API client from the npm registry:

npm install algoliasearch instantsearch.js instantsearch.css

yarn add algoliasearch instantsearch.js instantsearch.css

Import a theme to style the widget out of the box:

JavaScript

import "instantsearch.css/themes/satellite.css";

Add a container

The widget renders into a container element. Add one to your markup:

HTML

<div id="autocomplete"></div>

Provide a container (for example, a div), not an input. The widget generates a fully accessible search box for you. Unlike the standalone Autocomplete library, the autocomplete widget runs inside an InstantSearch instance. Create the instance, add the widget with addWidgets, then start the search:

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import instantsearch from "instantsearch.js";
import { autocomplete } from "instantsearch.js/es/widgets";

import "instantsearch.css/themes/satellite.css";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

const search = instantsearch({
  indexName: "instant_search",
  searchClient,
});

search.addWidgets([
  autocomplete({
    container: "#autocomplete",
    placeholder: "Search for products",
  }),
]);

search.start();

The widget is added to InstantSearch but it doesn’t show results until you configure the indices to query.

Display results from an index

Use the indices option to define which indices to query and how to display their results. Each index can declare its own templates and a getURL function to navigate when a user selects an item:

JavaScript

autocomplete({
  container: "#autocomplete",
  placeholder: "Search for products",
  indices: [
    {
      indexName: "instant_search",
      getURL: (item) => `/products/${item.objectID}`,
      searchParameters: {
        hitsPerPage: 5,
      },
      templates: {
        header: ({ items }, { html }) =>
          html`<div>Products (${items.length})</div>`,
        item: ({ item, onSelect }, { html, components }) =>
          html`<div onClick=${onSelect}>
            ${components.ReverseHighlight({ hit: item, attribute: "name" })}
          </div>`,
      },
    },
  ],
});

You can query several indices at once by adding more objects to the indices array. To learn more, see Including multiple result types.

Customize result templates

Each index renders with its own header, item, and noResults templates, and the widget accepts a top-level panel template for the overall layout. The Display results from an index section covers header and item.

Highlight the matched query

Item templates receive a components object with Highlight, ReverseHighlight, Snippet, and ReverseSnippet helpers that emphasize the part of an attribute matching the user’s query:

JavaScript

autocomplete({
  container: "#autocomplete",
  indices: [
    {
      indexName: "instant_search",
      templates: {
        item: ({ item }, { html, components }) =>
          html`<div>
            ${components.Highlight({ hit: item, attribute: "name" })}
          </div>`,
      },
    },
  ],
});

Use Snippet to highlight within a longer, truncated attribute, and the Reverse variants to emphasize the text that doesn’t match. This is a common style for Query Suggestions.

Show an empty state

The noResults template renders when an index returns nothing. If any index defines it, the panel stays open even when every index is empty, so you can show a helpful message:

JavaScript

autocomplete({
  container: "#autocomplete",
  indices: [
    {
      indexName: "instant_search",
      templates: {
        noResults: (_, { html }) => html`<div>No products found.</div>`,
      },
    },
  ],
});

Customize the panel layout

The top-level panel template controls the layout of the whole panel, including the order and grouping of recent searches, query suggestions, and each index. It receives an elements object whose keys are recent, suggestions, and each index’s indexName, so you can arrange sections into rows or columns—for example, suggestions on the left and results on the right:

JavaScript

autocomplete({
  container: "#autocomplete",
  templates: {
    panel: ({ elements }, { html }) =>
      html`<div class="aa-grid">
        <div class="aa-column">${elements.suggestions}</div>
        <div class="aa-column">${elements["instant_search"]}</div>
      </div>`,
  },
  // ...
});

The template only sets the markup. Style the columns with your own CSS:

CSS

.aa-grid {
  display: grid;
  grid-template-columns: 1fr 2fr;
  gap: 1rem;
}

Filter results

To narrow what an index returns, set Algolia search parameters on that index with searchParameters. You can apply filters, facetFilters, numericFilters, and other parameters per index:

JavaScript

autocomplete({
  container: "#autocomplete",
  indices: [
    {
      indexName: "instant_search",
      searchParameters: {
        hitsPerPage: 5,
        filters: "categories:Phones",
        facetFilters: [["brand:Apple", "brand:Samsung"]],
      },
    },
  ],
});

The widget applies these parameters to every query for that index. For an interactive filter UI inside the autocomplete—such as selectable tags or facet values that users add and remove—use the standalone Autocomplete library, which provides the tags plugin and facet sources.

Reshape and deduplicate results

Use transformItems to adjust results before they’re displayed—for example, to remove duplicates across indices or limit the number of items each index shows. The function receives an array with one entry per index, each shaped as { indexName, indexId, hits, results }, and must return the same shape:

JavaScript

autocomplete({
  container: "#autocomplete",
  indices: [
    { indexName: "instant_search" },
    { indexName: "instant_search_demo_query_suggestions" },
  ],
  transformItems(indices) {
    const seen = new Set();

    return indices.map((index) => ({
      ...index,
      hits: index.hits
        .filter((hit) => {
          if (seen.has(hit.objectID)) {
            return false;
          }
          seen.add(hit.objectID);
          return true;
        })
        .slice(0, 5),
    }));
  },
});

Unlike the standalone library’s reshape API, the widget doesn’t group or sort sources for you—deduplication and per-index limits are manual, as shown above.

Add Query Suggestions and recent searches

The widget can display query suggestions from a Query Suggestions index and recent searches stored in the browser’s local storage. Enable them with showQuerySuggestions and showRecent:

JavaScript

autocomplete({
  container: "#autocomplete",
  placeholder: "Search for products",
  showRecent: true,
  showQuerySuggestions: {
    indexName: "instant_search_demo_query_suggestions",
    getURL: (item) => `/search?q=${item.query}`,
  },
  indices: [
    {
      indexName: "instant_search",
      // ...
    },
  ],
});

To customize suggestions and recent searches, set a custom storage key, or refine your main index when a user selects a suggestion, see Build a Query Suggestions UI.

Send click and conversion events

To send click and conversion events when users interact with the autocomplete, enable insights on the InstantSearch instance:

JavaScript

const search = instantsearch({
  indexName: "instant_search",
  searchClient,
  insights: true,
});

The widget then sends view and click events automatically when users see and select results. Conversion events, like add-to-cart, usually happen after the user leaves the autocomplete, on the destination page. Send those where the conversion occurs with the Insights client. The autocomplete item template doesn’t expose a sendEvent function. The widget renders an accessible combobox, so users can operate it entirely from the keyboard—no extra configuration:

Up and Down arrows move through the items. The highlight wraps around at the ends of the list.
Enter opens the highlighted item, or submits the typed query when nothing is highlighted.
Escape closes the panel, then clears the highlight.
Tab closes the panel and moves focus to the next element.

What happens on Enter depends on how you handle navigation:

If the highlighted item’s index defines getURL, the browser opens that URL.
Otherwise, when you set getSearchPageURL, submitting the query sends the user to your search results page.
To use client-side routing instead of a full page load, provide an onSelect function and handle navigation in your app.

JavaScript

autocomplete({
  container: "#autocomplete",
  // On Enter with no highlighted item, open the search results page.
  getSearchPageURL: ({ query }) => `/search?q=${query}`,
  indices: [
    {
      indexName: "instant_search",
      // On Enter or click with a highlighted item, open its URL.
      getURL: (item) => `/products/${item.objectID}`,
    },
  ],
});

The widget also sets the matching ARIA roles (combobox, aria-expanded, aria-activedescendant), so screen readers announce the active item as users move through the list.

Enable detached (mobile) mode

On small screens, the widget can switch to a full-screen overlay. Use the detachedMediaQuery option to control when this happens. By default, detached mode activates at (max-width: 680px).

JavaScript

autocomplete({
  container: "#autocomplete",
  detachedMediaQuery: "(max-width: 1024px)",
  // ...
});

To turn off detached mode, set detachedMediaQuery to an empty string.

Explore advanced examples

Federated two-column autocomplete: a layout that combines recent searches, Query Suggestions, product previews, a quick-access panel, and category suggestions.
Rich text box with mentions: a headless ”@” mentions text box, built with the connectAutocomplete connector, that reproduces the X compose experience.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Open CodeSandbox

Explore source code

Install InstantSearch.js

Add a container

Add the widget to InstantSearch

Display results from an index

Customize result templates

Highlight the matched query

Show an empty state

Customize the panel layout

Filter results

Reshape and deduplicate results

Add Query Suggestions and recent searches

Send click and conversion events

Support keyboard navigation

Enable detached (mobile) mode

Explore advanced examples

See also

Open CodeSandbox

Explore source code

​Install InstantSearch.js

​Add a container

​Add the widget to InstantSearch

​Display results from an index

​Customize result templates

​Highlight the matched query

​Show an empty state

​Customize the panel layout

​Filter results

​Reshape and deduplicate results

​Add Query Suggestions and recent searches

​Send click and conversion events

​Support keyboard navigation

​Enable detached (mobile) mode

​Explore advanced examples

​See also

Install InstantSearch.js

Add a container

Add the widget to InstantSearch

Display results from an index

Customize result templates

Highlight the matched query

Show an empty state

Customize the panel layout

Filter results

Reshape and deduplicate results

Add Query Suggestions and recent searches

Send click and conversion events

Support keyboard navigation

Enable detached (mobile) mode

Explore advanced examples

See also