> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# createQuerySuggestionsPlugin

> This plugin adds Query Suggestions to Autocomplete.

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

<Tip>
  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](/doc/api-reference/widgets/autocomplete/js) or
  [React InstantSearch](/doc/api-reference/widgets/autocomplete/react).
</Tip>

## Index setup

Before using the query suggestions plugin,
you need to create an Algolia <Index /> with the expected format.
You can either use the [dashboard](https://dashboard.algolia.com/query-suggestions),
or [use the API clients](/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js).

## Installation

First, you need to install the plugin.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/autocomplete-plugin-query-suggestions
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/autocomplete-plugin-query-suggestions
  ```
</CodeGroup>

Then import it in your project:

```js JavaScript icon=code theme={"system"}
import { createQuerySuggestionsPlugin } from "@algolia/autocomplete-plugin-query-suggestions";
```

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

```html HTML icon=code-xml theme={"system"}
<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`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js),
along with the [`algoliasearch`](https://www.npmjs.com/package/algoliasearch) API client.

```js JavaScript icon=code theme={"system"}
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](/doc/ui-libraries/autocomplete/api-reference/autocomplete-plugin-recent-searches/createLocalStorageRecentSearchesPlugin) plugin, as follows:

```js JavaScript icon=code theme={"system"}
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](https://codesandbox.io/s/github/algolia/autocomplete/tree/next/examples/query-suggestions-with-recent-searches).

## Parameters

<ParamField body="searchClient" type="SearchClient" required>
  The initialized Algolia search client.
</ParamField>

<ParamField body="indexName" type="string" required>
  The index name.
</ParamField>

<ParamField body="getSearchParams" type="(params: { state: AutocompleteState }) => SearchParameters">
  A function returning [Algolia search parameters](/doc/api-reference/search-api-parameters).
</ParamField>

<ParamField body="transformSource" type="(params: { source: AutocompleteSource, state: AutocompleteState, onTapAhead: () => void })">
  This function takes the original [source](/doc/ui-libraries/autocomplete/core-concepts/sources) 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](/doc/ui-libraries/autocomplete/core-concepts/state):

  ```js JavaScript icon=code theme={"system"}
  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:

  <CodeGroup>
    ```js JavaScript icon=code theme={"system"}
    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>`;
            },
          },
        };
      },
    });
    ```

    ```jsx JSX icon=code theme={"system"}
    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>
              );
            },
          },
        };
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="categoryAttribute" type="string | string[]">
  The attribute or attribute path to display categories for.

  ```js JavaScript icon=code theme={"system"}
  const querySuggestionsPlugin = createQuerySuggestionsPlugin({
    searchClient,
    indexName: "instant_search_demo_query_suggestions",
    categoryAttribute: [
      "instant_search",
      "facets",
      "exact_matches",
      "hierarchicalCategories.lvl0",
    ],
  });
  ```
</ParamField>

<ParamField body="itemsWithCategories" type="number" default={1}>
  How many items to display categories for.
</ParamField>

<ParamField body="categoriesPerItem" type="number" default={1}>
  The number of categories to display per item.
</ParamField>