Autocomplete

Shows search results as users type their query in a search box.

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

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.

Signature

<EXPERIMENTAL_Autocomplete
  indices={array}
  showSuggestions={object}
  onSelect={function}
  getSearchPageURL={function}
  searchParameters={object}
  panelComponent={function}
  classNames={object}
/>

Import

JavaScript

import { EXPERIMENTAL_Autocomplete } from "react-instantsearch";

About this widget

<Autocomplete> is one of the most common widgets in a search UI. With this widget, users can get search results as they type their query.

This widget includes a “showSuggestions” feature that displays query suggestions from a separate index.

Examples

JavaScript

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

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <EXPERIMENTAL_Autocomplete
        indices={[
          {
            indexName: "instant_search",
            getQuery: (item) => item.name,
            getUrl: (item) => `/search?q=${item.name}`,
            headerComponent: () => <div>Products</div>,
            itemComponent: ({ item, onSelect }) =>
              <div onClick={onSelect}>{item.name}</div>,
          },
        ]}
        showSuggestions={{
          indexName: "query_suggestions",
        }}
      />
    </InstantSearch>
  );
}

Props

indices · array · required

An array of objects that define the indices to query and how to display the results.

• indexName: the name of the index to query
• getQuery: preprocess the query before it is sent for search
• getUrl: update the url to send the search request
• searchParameters: additional search parameters to send with the search request
• headerComponent: component to render for the header of the index
• itemComponent: component to render for each result from a query

JavaScript

<EXPERIMENTAL_Autocomplete
  indices={[
    {
      indexName: "instant_search",
      getQuery: (query) => query,
      getURL: (item) => `/search/?q=${item.query}`,
      searchParameters: {
        hitsPerPage: 5,
      },
      headerComponent: ({ items }) =>
        <div>Products ({items.length} results)</div>,
      itemComponent: ({ item, onSelect }) =>
        <div onClick={onSelect}>{item.name}</div>
    },
  ]}
/>

showSuggestions · object

Configures the query suggestions feature.

• indexName: the name of the index to query for suggestions
• getURL: update the url to send the search request
• headerComponent: component to render for the header of the index
• itemComponent: component to render for each suggestion

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  showSuggestions={{
    indexName: "query_suggestions",
    getURL: (item) => `/search?q=${item.query}`,
    headerComponent: ({ items }) =>
      <div>Suggestions ({items.length} results)</div>,
    itemComponent: ({ item, onSelect }) =>
      <div onClick={onSelect}>{item.query}</div>,
  }}
/>

searchParameters · object

Additional search parameters to send with the search request for every index.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  searchParameters={{
    hitsPerPage: 5,
  }}
/>

onSelect · function

A function that is called when the user selects an item. If not provided, the default implementation:

• navigates to the URL of an item if the index configuration defines getURL();
• or navigates to the URL of the search page if autocomplete is not in a search page and getSearchPageURL() is defined;
• or otherwise refines the query

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  onSelect={({ query, setQuery, url }) => {
    if (inSearchPage && !url) {
      setQuery(query);
      return;
    }
    
    window.location.href = url || `/search?q=${query}`;
  }}
/>

getSearchPageURL · function

A function that returns the URL of the search page for a given search state.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  getSearchPageURL={(nextUiState) => {
    return `/search?q=${qs.stringify(nextUiState)}`;
  }}
/>

panelComponent · function

Use the component to customize how the panel is rendered. This is useful when implementing layouts with multiple rows or columns.

The component receives a prop containing:

• elements: a key-value dictionary of indices to render. These include regular index names, and special elements like recent and suggestions, if applicable.
• indices: an array containing the data for each index.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  panelComponent={({ elements, indices }) => (
    <div>
      <p>My custom panel</p>
      <div className="left">{elements.suggestions}</div>
      <div className="right">{elements.instant_search}</div>
    </div>
  )}
/>

classNames · object

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• root. The widget’s root element.
• list. The list of results.
• item. The list of items.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  classNames={{
    root: "MyCustomAutocomplete",
    list: ["MyCustomAutocompleteList", "MyCustomAutocompleteList--subclass"],
    item: "MyCustomAutocompleteItem"
  }}
/>