createQuerySuggestionsPlugin

This plugin adds Query Suggestions to Autocomplete.

Autocomplete is also available as an experimental widget in InstantSearch, making it easier to integrate into your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

Index setup

Before using the query suggestions plugin, you need to create an Algolia with the expected format. You can either use the dashboard, or use the API clients.

Installation

First, you need to install the plugin.

npm

npm install @algolia/autocomplete-plugin-query-suggestions

yarn add @algolia/autocomplete-plugin-query-suggestions

Then import it in your project:

JavaScript

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

If you don’t use a package manager, you can use the HTML script element:

HTML

<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-query-suggestions@1.19.9/dist/umd/index.production.js"
  integrity="sha256-4F+juIHMxmpot1dHUAyn4gbMRfVFs/I9k6WsoFEFQqk="
  crossorigin="anonymous"
></script>
<script>
  const { createQuerySuggestionsPlugin } =
    window["@algolia/autocomplete-plugin-query-suggestions"];
</script>

Example

This example uses the plugin within autocomplete-js, along with the algoliasearch API client.

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { autocomplete } from "@algolia/autocomplete-js";
import { createQuerySuggestionsPlugin } from "@algolia/autocomplete-plugin-query-suggestions";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
});

autocomplete({
  container: "#autocomplete",
  plugins: [querySuggestionsPlugin],
});

Combine this plugin with the recent searches plugin, as follows:

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { autocomplete } from "@algolia/autocomplete-js";
import { createLocalStorageRecentSearchesPlugin } from "@algolia/autocomplete-plugin-recent-searches";
import { createQuerySuggestionsPlugin } from "@algolia/autocomplete-plugin-query-suggestions";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  key: "navbar",
});
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
  getSearchParams() {
    return recentSearchesPlugin.data.getAlgoliaSearchParams();
  },
});

autocomplete({
  container: "#autocomplete",
  openOnFocus: true,
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
});

To see it in action, check this demo on CodeSandbox.

Parameters

searchClient · SearchClient · required

The initialized Algolia search client.

indexName · string · required

The index name.

getSearchParams · (params: { state: AutocompleteState }) => SearchParameters

A function returning Algolia search parameters.

transformSource · (params: { source: AutocompleteSource, state: AutocompleteState, onTapAhead: () => void })

This function takes the original source as a parameter and returns a modified version of that source.

Example: change Autocomplete state

Usually, when a link in the Autocomplete menu is selected, the menu closes. However, to keep the menu visible after a selection is made, use transformSource to set the isOpen state:

JavaScript

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
  transformSource({ source, onTapAhead }) {
    return {
      ...source,
      onSelect({ setIsOpen }) {
        setIsOpen(true);
      },
    };
  },
});

Example: create links

Turns Query Suggestions into clickable Google search links:

JavaScript

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
  transformSource({ source, onTapAhead }) {
    return {
      ...source,
      getItemUrl({ item }) {
        return `https://google.com?q=${item.query}`;
      },
      templates: {
        ...source.templates,
        item(params) {
          const { item, html } = params;

          return html`<a
            class="aa-ItemLink"
            href="https://google.com?q=${item.query}"
          >
            ${source.templates.item(params).props.children}
          </a>`;
        },
      },
    };
  },
});

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
  transformSource({ source, onTapAhead }) {
    return {
      ...source,
      getItemUrl({ item }) {
        return `https://google.com?q=${item.query}`;
      },
      templates: {
        ...source.templates,
        item(params) {
          const { item } = params;

          return (
            <a
              className="aa-ItemLink"
              href={`https://google.com?q=${item.query}`}
            >
              {source.templates.item(params).props.children}
            </a>
          );
        },
      },
    };
  },
});

categoryAttribute · string | string[]

The attribute or attribute path to display categories for.

JavaScript

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: "instant_search_demo_query_suggestions",
  categoryAttribute: [
    "instant_search",
    "facets",
    "exact_matches",
    "hierarchicalCategories.lvl0",
  ],
});

itemsWithCategories · number · default: 1

How many items to display categories for.

categoriesPerItem · number · default: 1

The number of categories to display per item.