Autocomplete

Learn how to build an autocomplete search experience with React InstantSearch.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

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.

Algolia provides a full-featured solution to build autocomplete experiences with React 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 React InstantSearch implementation to create this kind of experience.

This widget is and is subject to change in minor versions.

Install React InstantSearch

The <Autocomplete> widget is part of React InstantSearch. Install React InstantSearch and the Algolia API client from the npm registry:

npm

npm install algoliasearch react-instantsearch instantsearch.css

yarn add algoliasearch react-instantsearch instantsearch.css

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

JavaScript

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

Add the widget to InstantSearch

Render the <EXPERIMENTAL_Autocomplete> component inside an <InstantSearch> provider:

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, EXPERIMENTAL_Autocomplete } from "react-instantsearch";

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

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

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <EXPERIMENTAL_Autocomplete placeholder="Search for products" />
    </InstantSearch>
  );
}

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 prop to define which indices to query and how to display their results. In React, you provide React components with headerComponent and itemComponent, and a getURL function to navigate when a user selects an item:

JavaScript

<EXPERIMENTAL_Autocomplete
  placeholder="Search for products"
  indices={[
    {
      indexName: "instant_search",
      getURL: (item) => `/products/${item.objectID}`,
      searchParameters: { hitsPerPage: 5 },
      headerComponent: ({ items }) => <div>Products ({items.length})</div>,
      itemComponent: ({ item, onSelect }) => (
        <button type="button" onClick={onSelect}>
          {item.name}
        </button>
      ),
    },
  ]}
/>

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

Customize result templates

Each index renders with headerComponent, itemComponent, and noResultsComponent, and the widget accepts a top-level panelComponent for the overall layout. The Display results from an index section covers headerComponent and itemComponent.

Highlight the matched query

Use the <Highlight> component from react-instantsearch in an item component to emphasize the part of an attribute matching the user’s query:

JavaScript

import { Highlight } from "react-instantsearch";

<EXPERIMENTAL_Autocomplete
  indices={[
    {
      indexName: "instant_search",
      itemComponent: ({ item }) => <Highlight hit={item} attribute="name" />,
    },
  ]}
/>;

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

Show an empty state

The noResultsComponent 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

<EXPERIMENTAL_Autocomplete
  indices={[
    {
      indexName: "instant_search",
      itemComponent: ({ item }) => <div>{item.name}</div>,
      noResultsComponent: () => <div>No products found.</div>,
    },
  ]}
/>

Customize the panel layout

The top-level panelComponent 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

<EXPERIMENTAL_Autocomplete
  panelComponent={({ elements }) => (
    <div className="aa-grid">
      <div className="aa-column">{elements.suggestions}</div>
      <div className="aa-column">{elements["instant_search"]}</div>
    </div>
  )}
  indices={[
    {
      indexName: "instant_search",
      itemComponent: ({ item }) => <div>{item.name}</div>,
    },
  ]}
/>

The component 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

<EXPERIMENTAL_Autocomplete
  indices={[
    {
      indexName: "instant_search",
      itemComponent: ({ item }) => <div>{item.name}</div>,
      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 the transformItems prop 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

<EXPERIMENTAL_Autocomplete
  indices={[
    {
      indexName: "instant_search",
      itemComponent: ({ item }) => <div>{item.name}</div>,
    },
    {
      indexName: "instant_search_demo_query_suggestions",
      itemComponent: ({ item }) => <div>{item.query}</div>,
    },
  ]}
  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 the showQuerySuggestions and showRecent props:

JavaScript

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

To template 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 the insights prop on the <InstantSearch> provider:

JavaScript

<InstantSearch indexName="instant_search" searchClient={searchClient} insights>
  {/* ... */}
</InstantSearch>

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 component doesn’t expose a sendEvent function.

Support keyboard navigation

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 navigate yourself.

JavaScript

<EXPERIMENTAL_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}`,
      itemComponent: ({ item }) => <div>{item.name}</div>,
    },
  ]}
/>

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 prop to control when this happens. By default, detached mode activates at (max-width: 680px).

JavaScript

<EXPERIMENTAL_Autocomplete
  detachedMediaQuery="(max-width: 1024px)"
  placeholder="Search for products"
/>

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 useAutocomplete hook, that reproduces the X compose experience.

See also

• <Autocomplete> widget reference for the full list of props.
• Build a Query Suggestions UI.