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"></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 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],
});

You can combine this plugin with the Recent Searches plugin to leverage the empty screen with recent and popular queries.

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 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

Parameter Description
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 })

A function to transform the provided source.

Keeping the panel open on select:

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);
      },
    };
  },
});

Opening a link:

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?