UI libraries / Autocomplete / API reference / autocomplete-plugin-query-suggestions

createQuerySuggestionsPlugin

The Query Suggestions plugin adds Algolia Query Suggestions to your autocomplete.

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, or use the API clients.

Installation

First, you need to install the plugin.

Copy 
1
2
3

yarn add @algolia/autocomplete-plugin-query-suggestions
# or
npm install @algolia/autocomplete-plugin-query-suggestions

Then import it in your project:

Copy 
1

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

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

Copy 
1
2
3
4
5
6

<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-query-suggestions@1.17.4/dist/umd/index.production.js" integrity="sha256-+zshgCJ9l7NdLUZXhUhr3GJkl27v02UAY5oD80vMYWs=" 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.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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
type: SearchClient
Required

The initialized Algolia search client.
indexName
type: string
Required

The index name.
getSearchParams
type: (params: { state: AutocompleteState }) => SearchParameters

A function returning Algolia search parameters.
transformSource
type: (params: { source: AutocompleteSource, state: AutocompleteState, onTapAhead: () => void })

This function takes the original source as a parameter and returns a modified version of that source. For 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:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

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

Create links

Turns Query Suggestions into clickable Google search links:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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>`;
        },
      },
    };
  },
});
categoryAttribute
type: string | string[]

The attribute or attribute path to display categories for.
Copy 
1
2
3
4
5
6
7
8
9
10

const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: 'instant_search_demo_query_suggestions',
  categoryAttribute: [
    'instant_search',
    'facets',
    'exact_matches',
    'hierarchicalCategories.lvl0',
  ],
});
itemsWithCategories
type: number
default: 1

How many items to display categories for.
categoriesPerItem
type: number
default: 1

The number of categories to display per item.
Previous
autocomplete-plugin-query-suggestions
Next
autocomplete-plugin-algolia-insights
Did you find this page helpful?