Conditional display in InstantSearch.js

This guide describes what to do when there are no results, when there’s no query, or when there are errors.

If you want to feature content in your search results based on a set of conditions, you can use Rules to:

• Feature specific data from within your records to, for example, show promotional prices during a sales period
• Display advertisements or promotional banners.

Handling no results

Since not all queries lead to results, it’s essential to let users know when this happens by providing hints on how to adjust the query.

Display a message

The easiest way to display a fallback message when a query doesn’t return results is to use the templates.empty option.

All examples in this guide assume you’ve included InstantSearch.js in your web page from a CDN. If you’re using it with a package manager, you should adjust how you import InstantSearch.js and its widgets. Read How to install InstantSearch.js for more information.

1
2
3
4
5
6
7
8
search.addWidgets([
  instantsearch.widgets.hits({
    container: 'hits',
    templates: {
      empty: '<div>No results have been found for {{ query }}</div>.'
    }
  })
]);

The preceding example also works with infiniteHits.

Let the user clear all filters

If a user makes a mistake, they may not find any results. You can account for this by providing a way to clear filters right from the “no results” state so they can start over.

For this purpose, you can use the clearRefinements widget. However, you can’t use it inside the empty template, so you must use routing instead.

First, activate the URL sync mechanism to clear the filters using the URL.

1
2
3
const search = instantsearch({
  routing: true
});

Check out the complete routing guide if you want to learn more.

Routing makes your InstantSearch.js app aware of changes in the URL. By removing URL parameters, you can influence search parameters and clear filters.

1
2
3
4
5
6
7
8
9
10
11
search.addWidgets([
  instantsearch.widgets.hits({
    container: 'hits',
    templates: {
      empty: `<div>
                <p>No results have been found for {{ query }}</p>
                <a role="button" href=".">Clear all filters</a>
              </div>`
    }
  })
]);

Handling empty queries

By default, InstantSearch.js always shows you results, even when the query is empty. Depending on your use case and how you build your UI, you may only want to show results when there’s a query.

Using the helper state

Using the helper state hides the results container when the query is empty:

1
2
3
4
5
6
7
8
const search = instantsearch({
  searchFunction(helper) {
    const container = document.querySelector('#results');
    container.style.display = helper.state.query === '' ? 'none' : '';

    helper.search();
  }
});

Using a connector

The following example uses the connectHits connector.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const customHits = instantsearch.connectors.connectHits(
  (renderOptions, isFirstRender) => {
    const { results, widgetParams } = renderOptions;
    const { container } = widgetParams;

    container.innerHTML =
      results && results.query
        ? `<div>Searching for query "${results.query}".</div>`
        : `<div>No query</div>`;
  }
);

search.addWidgets([
  customHits({
    container: document.querySelector('#hits')
  })
]);

Handling errors

If an error occurs, you can display a specific piece of content to help the user return to the standard state.

Making an error-handling widget

You can build a custom widget to handle errors. If you want to learn more about custom widgets, check out the guide.

1
2
3
4
5
6
7
8
9
search.addWidgets([
  {
    init({ helper }) {
      helper.on('error', error => {
        console.error('Error', error);
      });
    }
  }
]);

You can improve this custom widget by writing a more meaningful error message, adapting it to your UI, figuring out whether the user is online, and logging the error in your monitoring system.