Predictive search suggestions

Predictive search suggestions lets users quickly access the content they’re looking for because the most relevant suggestions appear directly inside the search box. They can also see the most popular searches and discover more of your content.

View demo View source code

Before you begin

This guide requires InstantSearch.js and a Query Suggestions index. If you already have one, go directly to the detailed implementation overview.

Implementation guide

Create a Query Suggestions index

Go to the Query suggestions tab of the dashboard.
Click the New Query Suggestion button.
Fill in the relevant “Name”, “Languages”, and “Source Index” inputs, then click the Accept button.

For more information, see Query Suggestions.

High-level overview

To create predictive search suggestions, you overlap two containers (a search box and a predictive box), then send your user’s current query to your suggestions index at every keystroke. Based on the query, the predictive box displays and consistently updates the first result from the suggestions. You can also display other results under the search box (in a drop-down menu or a grid).

Wrap your search input in a container (for example, a <div>).
Declare a second container within the first one. This second container displays the suggestions.
Use CSS to adjust the position of the search box so that it perfectly overlaps with the suggestions container.
Change the text color of the suggestion container so that the query and the recommendation are distinctive.
At every keystroke, send the query to your Query Suggestions index.
Every time you get a response from the Query Suggestions index, update the text in your suggestions container with the first result that starts with the same letters as the input query. You can also display other suggestions beneath your search box if you want.

Predicted suggestions must begin with the same letters as your user’s input.

Detailed overview

This guide walks you through creating a predictive search box widget, which you can import into your app.

Create search box

Write a render function that creates a search box with three <div>s:

The search box,
The overlapping predictive box
A display area for extra suggestions.

JavaScript

const renderSearchBoxContainer = (placeholder, value) => {
  return `
      <div id="searchbox">
        <div id="predictive-box" style="display: none;">
          <span id="predictive-box-text"></span>
        </div>
        <div class="search-box-container">
          <input autocapitalize="off"
            placeholder="${placeholder}"
            id="search-box-input"
            autocomplete="off"
            autocorrect="off"
            role="textbox"
            spellcheck="false"
            type="search"
            value="${value}">
        </div>
        <div id="clear-input"><i class="fas fa-times"></i></div>
        <fieldset id="suggestion-tags-container"></fieldset>
      </div>
    `;
};

The search box is composed of three main parts. This guide refers to them as:

The search box: the input field where users type in their search queries (.search-box-container).
The predictive box: the <div> that overlaps with the search box and contains the top suggestion (.predictive-box).
The suggestions tags: the <div> that contains all the extra suggestions from the Query Suggestions index (.suggestion-tags-container).

Style the search box

Write the CSS to style the search box and predictive box. The goal is to ensure:

The <div>s overlap perfectly
The predictive box appears behind the search box (so that your users can still type their queries)
The predictive box and search box have different text colors.

CSS

.search-box-container input {
  border: none;
  border-bottom: 1px solid #cecece;
  width: 100%;
  font-size: 20px;
  background: transparent;
  padding: 0 !important;
  outline: none;
  height: 100%;
  position: relative;
  z-index: 99;
  font-family: Arial, Helvetica, sans-serif;
}

#predictive-box {
  height: 49px;
  padding: 0 !important;
  display: flex;
  align-items: center;
  position: absolute;
  border-bottom: 1px solid transparent;
}

#predictive-box-text {
  font-family: Arial, Helvetica, sans-serif;
  font-size: 20px;
  color: #a2a2a2;
}

This guide doesn’t include the complete CSS. You can find it in the source code.

Detect user key press

Define a helper function that checks if users have pressed a specific key.

JavaScript

const isKey = (event, code, name) => event.which === code || event.keyCode === code || event.key === name;

Create a predictive search box

Create a PredictiveSearchBox class. You’ll add methods in the following steps.
JavaScript
class PredictiveSearchBox { // Add methods to the class in the following steps }

Add a constructor for the PredictiveSearchBox.

JavaScript

class PredictiveSearchBox {
  constructor(options) {
    Object.assign(this, options);

    this.client = algoliasearch(options.appID, options.apiKey);
    this.querySuggestionsIndex = this.client.initIndex(
      this.querySuggestionsIndex
    );

    this.maxSuggestions = 5;
    this.tabActionSuggestion = '';
  }
}

Add an initialization method for the PredictiveSearchBox class.

JavaScript

class PredictiveSearchBox {
  // ...

  init(initOptions) {
    const widgetContainer = document.querySelector(this.container);

    if (!widgetContainer) {
      throw new Error(
        `Could not find widget container ${this.container} inside the DOM.`
      );
    }

    widgetContainer.innerHTML = renderSearchBoxContainer(
      this.placeholder,
      initOptions.helper.state.query
    );

    this.predictiveSearchBox = widgetContainer.querySelector('#predictive-box');
    this.predictiveSearchBoxItem = widgetContainer.querySelector(
      '#predictive-box-text'
    );
    this.clearButton = widgetContainer.querySelector('#clear-input');
    this.searchBoxInput = widgetContainer.querySelector('#search-box-input');
    this.suggestionTagsContainer = widgetContainer.querySelector(
      '#suggestion-tags-container'
    );

    this.registerSearchBoxHandlers(
      initOptions.helper,
      this.searchBoxInput,
      this.clearButton
    );
  }
}

JavaScript

class PredictiveSearchBox {
  // ...

  registerSearchBoxHandlers = (helper, searchBox, clearButton) => {
    searchBox.addEventListener('input', event => this.updateTabActionSuggestion(event));
    searchBox.addEventListener('keydown', event => this.onTabSelection(event));
    clearButton.addEventListener('click', event => this.clear(event));
    searchBox.addEventListener('input', event => {
      helper.setQuery(event.currentTarget.value).search();
    });
  };
}

Add setter method

Add a setter method for the value of the search box input.

JavaScript

class PredictiveSearchBox {
  // ...

  setSearchBoxValue = value => {
    this.searchBoxInput.value = value;
    this.searchBoxInput.dispatchEvent(new Event('input'));
  };
}

Set search box value to the suggestion in the predictive search box

Add a handler method that calls setSearchBoxValue to set the search box value to the suggestion displayed in the predictive box when users press the right arrow.

JavaScript

class PredictiveSearchBox {
  // ...

  onTabSelection = event => {
    if (!isKey(event, 39, 'ArrowRight')) return;

    event.preventDefault();
    this.setSearchBoxValue(this.tabActionSuggestion);
  };
}

Update suggestions

Add a method that updates the suggestions tags based on the new hits from the query response.

JavaScript

class PredictiveSearchBox {
  // ...

  updateSuggestionTags = hits => {
    if (!this.maxSuggestions || this.maxSuggestions <= 0) return hits;
    this.clearSuggestionTags();

    hits.slice(0, this.maxSuggestions).forEach(suggestion => {
      const suggestionElement = document.createElement('button');
      suggestionElement.classList.add('suggestion-tag');
      suggestionElement.innerHTML = suggestion._highlightResult.query.value;

      suggestionElement.addEventListener('click', () => {
        this.setSearchBoxValue(suggestion.query);
      });
      this.suggestionTagsContainer.append(suggestionElement);
    });
  };
}

Search Query Suggestions index

Add a method that dispatches a search on your Query Suggestions index and uses the results to update the suggestions in the predictive box and suggestions tags. This method triggers whenever the query changes.

JavaScript

class PredictiveSearchBox {
  // ...

  updateTabActionSuggestion = event => {
    const query = event.currentTarget.value;

    if (!query) {
      this.predictiveSearchBox.style.display = 'none';
      this.clearButton.style.display = 'none';
      return;
    }

    this.querySuggestionsIndex
      .search({ query })
      .then(response => {
        const suggestions = response.hits.filter(hit =>
          hit.query.startsWith(query)
        );

        if (!suggestions.length) {
          this.clearPredictiveSearchBox();
          return [];
        }

        this.predictiveSearchBox.style.display = 'flex';
        this.predictiveSearchBoxItem.innerText = suggestions[0].query;
        this.tabActionSuggestion = suggestions[0].query;
        return suggestions.slice(1);
      })
      .then(this.updateSuggestionTags);
  };
}

Clear suggestions

Add a method that removes all suggestions tags so they can be updated.

JavaScript

class PredictiveSearchBox {
  // ...

  clearSuggestionTags = () => {
    this.suggestionTagsContainer.innerHTML = '';
  };
}

Add a method that removes the predictive box suggestion.

JavaScript

class PredictiveSearchBox {
  // ...

  clearPredictiveSearchBox = () => {
    this.tabActionSuggestion = '';
  };
}

Add a method that clears all suggestion content from your search container, letting you update it with new suggestions.

JavaScript

class PredictiveSearchBox {
  // ...

  clear = event => {
    this.searchBoxInput.value = '';
    this.predictiveSearchBoxItem.innerText = '';
    this.clearSuggestionTags();

    this.tabActionSuggestion = '';
    event.target.style.display = 'none';
    searchBoxInput.dispatchEvent(new Event('input'));
  };
}

Export predictive search box

Export the PredictiveSearchBox class so you can import it into your app.

JavaScript

class PredictiveSearchBox {
  // ...
}

export default PredictiveSearchBox;

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Predictive search suggestions

Before you begin

Implementation guide

Create a Query Suggestions index

High-level overview

Detailed overview

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

​Before you begin

​Implementation guide

​Create a Query Suggestions index

​High-level overview

​Detailed overview

Before you begin

Implementation guide

Create a Query Suggestions index

High-level overview

Detailed overview