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}
  showRecent={boolean | object}
  transformItems={function}
  onSelect={function}
  getSearchPageURL={function}
  searchParameters={object}
  panelComponent={function}
  classNames={object}
  placeholder={string}
  detachedMediaQuery={string}
/>

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>,
  }}
/>

showRecent · boolean | object

Configures the recent searches feature. Displays previously searched queries stored in local storage.

When set to true, uses default settings. When set to an object, you can configure:

• storageKey: the key to use in local storage (default: ais.recentSearches)
• headerComponent: component to render for the header above the recent searches list
• itemComponent: component to render for each recent search item (receives item, onSelect, and onRemoveRecentSearch props)
• classNames: CSS classes to customize the appearance

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  showRecent={true}
/>

{/* With customization */}
<EXPERIMENTAL_Autocomplete
  // ...
  showRecent={{
    storageKey: 'my-app-recent-searches',
    headerComponent: ({ items }) => (
      <div>Recent Searches</div>
    ),
    itemComponent: ({ item, onSelect, onRemoveRecentSearch }) => (
      <div>
        <button onClick={onSelect}>{item.query}</button>
        <button onClick={onRemoveRecentSearch}>×</button>
      </div>
    ),
  }}
/>

transformItems · function

Transforms the items before they are displayed. This function receives an array of index configurations with their hits and should return an array in the same format.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  transformItems={(indices) =>
    indices.map((index) => ({
      ...index,
      hits: index.hits.map((hit) => ({
        ...hit,
        _highlightResult: {
          ...hit._highlightResult,
          name: {
            ...hit._highlightResult.name,
            value: hit._highlightResult.name.value.toUpperCase(),
          },
        },
      })),
    }))
  }
/>

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"
  }}
/>

placeholder · string

Placeholder text for the search input.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  placeholder="Search for products..."
/>

detachedMediaQuery · string · default: "(max-width: 680px)"

Media query to enable detached (mobile) mode. When the media query matches, the autocomplete switches to a full-screen overlay with a modal interface optimized for mobile devices.

Set to an empty string to disable detached mode. When omitted, it defaults to the CSS variable --ais-autocomplete-detached-media-query, or "(max-width: 680px)" if the variable is not set.

JavaScript

<EXPERIMENTAL_Autocomplete
  // ...
  detachedMediaQuery="(max-width: 768px)"
/>

{/* Disable detached mode */}
<EXPERIMENTAL_Autocomplete
  // ...
  detachedMediaQuery=""
/>