Guides / Building Search UI / UI & UX patterns

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.

Query Suggestions help users search by showing a list of popular searches as search suggestions as they type. By selecting suggestions, users type less and avoid searches that don’t return any results.

Users often interact with Query Suggestions in an autocomplete menu. When typing, a list of suggestions appears below the search box. Choosing a suggestion initiates a search using that suggestion as the query.

Autocomplete menu with a query in the search box and a list of Query Suggestions below

Query Suggestions can also help in these cases:

  • To help users before they type anything. This is often combined with featured categories or featured search results.

  • To help users continue if a search didn’t return any results.

Explore related videos in the Algolia Academy

Explore Query Suggestions user interfaces

For examples of Query Suggestions in action, see:

For more information about building a Query Suggestions UI, see:

How Query Suggestions work

Algolia stores Query Suggestions as records in an index. This index is rebuilt every day, or when you change its settings. Each update runs through these steps:

  1. Find the most frequent searches from the search analytics of your source indices and their replicas. During the early stages of your implementation, when you haven’t gathered enough analytics, you can also generate suggestions using external analytics or your facets.

  2. Normalize and complete suggestions by removing duplicated, similar, or prefixed suggestions, depending on your settings. Suggestions must match the following criteria:

    • Only contain alphanumeric characters
    • Return a minimum number of search results
    • Longer than a minimum number of letters
    • Not be a banned expression.

    Query Suggestions also deduplicate similar searches, keeping only the most frequently searched terms as suggestions.

  3. Rank the suggestions by popularity (number of searches) in the last 30 days. For all similar searches, the individual counts are summed. Counts from external analytics are also added to the suggestion’s popularity.

Each suggestion in the Query Suggestions index has at least these attributes:

  • objectID. Unique record identifier, usually the suggestion itself
  • query. The suggestion
  • popularity. Number of searches in the last 30 days for the suggestion

If you add suggestions from facets, more attributes are added.

Set up Query Suggestions

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Algolia Search Search.
  3. Select your Algolia index:

    Select your Algolia application and index

  4. Open the Query Suggestions page and click New Query Suggestions Index.
  5. In the Source index field, enter the name of the index with the search results and provide a name for the Query Suggestions index. You can add more source indices later.
  6. Click Accept and Continue to start building the Query Suggestions index.

Augment Query Suggestions with external analytics

If you don’t have enough searches in your search analytics yet, or you want to add specific suggestions, you can upload external analytics from a JSON file:

  1. Prepare your suggestions in a JSON file. Each suggestion must have query and count attributes. The value of the count attribute is added to the value of the popularity attribute in the Query Suggestions index for that suggestion.

    You can tweak the popularity of existing suggestions by adding them to this JSON file and setting a high value for the count attribute.

    For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    [
      {
        "query": "shoes",
        "count": 10031
      },
      {
        "query": "dress shirt",
        "count": 731
      },
      {
        "query": "yellow jacket",
        "count": 122
      }
    ]
    
  2. Import this JSON file into Algolia as a new index.
  3. Now, create a Query Suggestions index for the imported analytics data. On the Query Suggestions page in the Algolia dashboard, click New Query Suggestions Index: the Source index is the index you created in the previous step.
  4. In the Data sources section, click Enable next to the External Analytics option.
  5. Enter the name of the index you imported in step 2 as the External analytics index.

Augment Query Suggestions with facet data

If you don’t have enough data from search analytics or external analytics, Query Suggestions can create suggestions from the combination of facet values. For example, for the facets color and brand, these Query Suggestions are created:

  • red nike
  • blue nike
  • red adidas
  • blue adidas

Suggestions created from facets are less relevant than those created by search analytics since they aren’t based on popularity. But they can still enrich the suggestions, especially for rarer queries. That’s why it’s best to keep suggestions from facets, even after you collect sufficient data from analytics.

To augment your Query Suggestions with facet data:

  1. Set appropriate searchable attributes and attributes for faceting.

  2. On the Query Suggestions page in the Algolia dashboard, select your Query Suggestions index.

  3. In the Data sources section, click Enable for Queries by facets.

  4. Select two facet attributes and click Add attributes. Repeat for any combination of two facets for which you want to generate suggestions.

To show categories from facets in your suggestions, see Query Suggestions with categories.

Optimize Query Suggestions

After the initial setup, you can optimize your experience with one of the following strategies.

Improve relevance

A Query Suggestions index is a regular Algolia index, so you can use the same features and settings to tune the relevance of your suggestions.

Query Suggestions with categories

You can make your suggestions more targeted by adding categories:

  1. Make sure you configure your category attribute as a facet.

  2. On the Query Suggestions page, select your Query Suggestions index.

  3. On the Overview & Settings tab, in the Categories section, click Edit categories.

  4. In the Categories attribute field, choose a category to display. In the Show top field, select how many top categories to display. For example, if you chose 2, the top two categories are added to every suggestion.

Query Suggestions with inline categories

How to determine top categories

Query Suggestions determines the top categories with the following algorithm:

  1. Perform a “strict” search with the suggestion in the source index—without features such as prefixing or typo-tolerance.
  2. Add the most frequently found category values to the facets.exact_matches attribute.
  3. Get the top filters (most often applied) for this search term from analytics and add them to the facets.analytics attribute.

The category information is added to each record in your Query Suggestions index.

For your user interface, it’s better to rely on the facets.exact_matches attribute because it represents data from your index. For example, if users often filter by a specific category, but you don’t have many items in that category, they won’t see many results when accepting this suggestion.

Display categories in your UI

Once you have categorized your Query Suggestions, decide how to display them in your frontend. One option is to redirect users to an InstantSearch page on category selection. This page uses the chosen category as a filter with the user’s initial query pre-filled in the search box. For an example of this, see Build a Query Suggestions UI with InstantSearch.

Remove duplicate or unhelpful suggestions

On the Query Suggestions page, select your Query Suggestions index, and adjust the following settings to improve the quality of the suggestions:

  • In the Languages field, add the language of your index. This lets Query Suggestions automatically remove duplicate suggestions such as singulars and plurals.

  • Adjust the Minimum letters setting to prevent short, incomplete suggestions. A suggestion must have at least this many letters to be included.

  • Adjust the Minimum hits setting to ensure enough search results are returned. A suggestion must return at least this many search results to be included.

  • On the Banned expressions tab, add expressions or patterns for excluding suggestions.

Personalize Query Suggestions

To add personalized Query Suggestions, follow these steps:

  1. On the Query Suggestions page, select your Query Suggestions index.

  2. On the Overview & Settings tab, in the Settings section, enable Personalized Query Suggestions.

Algolia then retrieves the top 20 facet values (based on your personalization strategy) from your source index and adds new attributes to the suggestions in your Query Suggestions index for each facet defined in your personalization strategy.

Generate different suggestions for different environments

You can use analytics tags to create different suggestions for different environments, such as mobile or desktop users, or for different geographical regions.

  1. Create a new Query Suggestions index with a recognizable name. For example, include the analytics tag in the name, such as products_query_suggestions_mobile.
  2. After creating the index, on the Overview & Settings tab, in the Data sources section, click Manage next to Algolia Analytics API.
  3. Enter the appropriate analytics tags. For example, products_query_suggestions_mobile. This only includes suggestions with specific analytics tags.

In your UI, you can target the different Query Suggestions indices depending on the user’s device or geographical region.

Troubleshoot missing Query Suggestions

If suggestions are missing, the Query Suggestions API can help identify the issue. For example, run the following command to retrieve the most recent log entries.

$
$
$
curl -H "x-algolia-api-key: ${YourAdminAPIKey}" \
     -H "x-algolia-application-id: ${YourApplicationID}" \
    "https://query-suggestions.us.algolia.com/1/logs/${YourQuerySuggestionsIndex}"

The log entries provide the following details:

For more information, see Get a log file.

Query Suggestions index schema

The following example shows a record from a Query Suggestions index with categories from facets.

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "query": "phone charger",    // The suggestion
  "objectID": "phone charger", // Unique identifier
  "popularity": 2457,          // Number of searches for this suggestion in the last 30 days
  "nb_words": 2,               // Number of words in the suggestion
  "products": {                // Name of the source index
    "exact_nb_hits": 42,       // Number of search results for this suggestion
    "facets": {
      "exact_matches": {       // Most frequent facet values found for this suggestion
        "brand": [
          { "value": "Anker", "count": 12 },  // This means 12 of the search results have "Anker" as "brand"
          { "value": "Yootech", "count": 11 },
          { "value": "TOZO", "count": 9 },
          { "value": "Aukey", "count": 4 },
          { "value": "Apple", "count": 2 }
        ]
      },
      "analytics": {          // Most frequently applied filters for this suggestion
        "brand": [
          {
            "attribute": "brand",
            "count": 347,
            "operator": ":",
            "value": "Anker"
          },
          {
            "attribute": "brand",
            "count": 203,
            "operator": ":",
            "value": "Apple"
          },
          {
            "attribute": "brand",
            "count": 152,
            "operator": ":",
            "value": "TOZO"
          },
          {
            "attribute": "brand",
            "count": 128,
            "operator": ":",
            "value": "Yootech"
          },
          {
            "attribute": "brand",
            "count": 80,
            "operator": ":",
            "value": "Aukey"
          }
        ]
      }
    }
  }
}

See also

Did you find this page helpful?