Build a Query Suggestions UI with React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Refine your results with the suggestions

The first step is to set up an autocomplete component with Autocomplete. You can find more information in the guide on Using Autocomplete with React.

Copy
import React, { useEffect, useRef, createElement, Fragment } from 'react';
import { render } from 'react-dom';

import { autocomplete } from '@algolia/autocomplete-js';

import '@algolia/autocomplete-theme-classic';

export function Autocomplete(props) {
  const containerRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) {
      return;
    }

    const search = autocomplete({
      ...props,
      container: containerRef.current,
      renderer: { createElement, Fragment, render },
    });

    return () => search.destroy();
  }, [props]);

  return <div ref={containerRef} />;
}

Now that you have your Autocomplete component, you can create the multi-index search experience. To start, create a component that acts as the interface between Autocomplete and React InstantSearch.

Inside, the autocomplete-plugin-query-suggestions package provides the createQuerySuggestionsPlugin function for creating a Query Suggestions plugin out-of-the-box. It requires the same Algolia search client used for your React InstantSearch app and an indexName. The indexName is the name of your Query Suggestions index.

To apply the suggestion, you can implement the useInstantSearch() Hook. You also need to mount a <SearchBox> widget or use its Hook to have React InstantSearch handle its state.

Copy
import React, { useCallback, useMemo } from 'react';

import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';

import {
  useInstantSearch,
  useSearchBox,
} from 'react-instantsearch';

import { Autocomplete } from './Autocomplete';
import { searchClient } from './searchClient';

export function SearchBoxWithSuggestions() {
  const { setIndexUiState } = useInstantSearch();
  const { query } = useSearchBox();

  const plugins = useMemo(() => {
    const querySuggestionsPlugin = createQuerySuggestionsPlugin({
      indexName: 'instant_search_demo_query_suggestions',
      searchClient,
      transformSource({ source }) {
        return {
          ...source,
          onSelect({ item }) {
            setIndexUiState((indexUiState) => ({
              ...indexUiState,
              query: item.query,
            }));
          },
        };
      },
    });

    return [querySuggestionsPlugin];
  }, []);

  const initialState = useMemo(() => ({ query }), [query]);

  const onReset = useCallback(
    () =>
      setIndexUiState((indexUiState) => ({
        ...indexUiState,
        query: '',
      })),
    []
  );

  return (
    <Autocomplete
      placeholder="Search for products…"
      plugins={plugins}
      initialState={initialState}
      onReset={onReset}
    />
  );
}

That’s it. You have set up your autocomplete multi-index search experience, and users can now select a suggestion and use it to search the main index.

A typical use of autocomplete is to display both relevant categories and suggestions. Then when a user selects a suggestion, both the suggestion and the associated category are used to refine the search. For this example, the relevant categories are stored on the suggestions records. You must update your render function to display the categories with the suggestions. For simplicity and brevity of the code, assume that all suggestions have categories, but this isn’t the case in the actual dataset. Take a look at the complete example to see the actual implementation.

Copy
// ...

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  // ...
  categoryAttributes: [
    'instant_search',
    'facets',
    'exact_matches',
    'categories',
  ],
});

// ...
}

Now that you can display categories, you can use them to refine the main search. Mount a <Menu> widget or use its Hook, then update the UI state with setIndexUiState.

Copy
// ...

import {
  useInstantSearch,
  useMenu,
  useSearchBox,
} from 'react-instantsearch';

export function SearchBoxWithSuggestions() {
  const { setIndexUiState } = useInstantSearch();
  const { query } = useSearchBox();
  useMenu({ attribute: 'categories' });

  const plugins = useMemo(() => {
    const querySuggestionsPlugin = createQuerySuggestionsPlugin({
      indexName: 'instant_search_demo_query_suggestions',
      searchClient,
      categoryAttributes: ['instant_search', 'facets', 'exact_matches', 'categories'],
      transformSource({ source }) {
        return {
          ...source,
          onSelect({ item }) {
            setIndexUiState((indexUiState) => ({
              ...indexUiState,
              query: item.query,
              menu: {
                categories: item.__autocomplete_qsCategory || '',
              },
            }));
          },
        };
      },
    });

    return [querySuggestionsPlugin];
  }, []);

  const initialState = useMemo(() => ({ query }), [query]);

  const onReset = useCallback(
    () =>
      setIndexUiState((indexUiState) => ({
        ...indexUiState,
        query: '',
        menu: { categories: '' },
      })),
    []
  );

  return (
    <Autocomplete
      placeholder="Search for products…"
      plugins={plugins}
      initialState={initialState}
      onReset={onReset}
    />
  );
}

That’s it. Now when a suggestion’s category is selected, both the query and the category are applied to the main search.

If you are using React Native, you can achieve the same result with ease. Check out this source code example.

Did you find this page helpful?

Build a Query Suggestions UI with React InstantSearch

On this page

Refine your results with the suggestions

On this page

Build a Query Suggestions UI with React InstantSearch

On this page

Refine your results with the suggestions

Use the related categories in the autocomplete

On this page