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 results haven’t loaded, the search may still be in progress or the device may be offline. For more information, see No hits or is the search still in progress? If you want to feature content in your search results based on a set of conditions, you can use Algolia Rules to:

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

To learn how to suppress InstantSearch’s initial , see Conditional requests.

Handle searches without results

When a query doesn’t return results, display a message and suggest changing the query or clearing filters.

Display a message

To display a fallback message when a query doesn’t return results, use the templates.empty option.

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

JavaScript

search.addWidgets([
  instantsearch.widgets.hits({
    container: 'hits',
    templates: {
      empty: ({ query }, { html }) =>
        html`<div>No results have been found for ${ query }.</div>`
    }
  })
]);

The preceding example also works with infiniteHits.

If users apply an overly specific configuration, they may not find any results. Account for this by letting them reset filters from the “no results” display so they can start another search. Do this with the clearRefinements widget. However, you can’t use it inside the empty template, so must use routing instead. First, activate the URL sync mechanism:

JavaScript

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

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

JavaScript

search.addWidgets([
  instantsearch.widgets.hits({
    container: 'hits',
    templates: {
      empty: ({ query }, { html }) =>
        html`<div>
          <p>No results have been found for ${query}}</p>
          <a role="button" href=".">Reset all filters</a>
        </div>`,
    },
  }),
]);

Handle empty queries

By default, InstantSearch sends search requests even when the query is empty. To hide results until users enter a query, use the following code. This hides the results without preventing search requests.

Using `transformItems`

Using transformItems to display no results when the query is empty:

JavaScript

hits({
  transformItems(items, { results }) {
    if (results.query === '') return [];

    return items;
  },
  templates: {
    empty(results, { html }) {
      if (results.query === '') return null;

      return html`No results found for "${results.query}"`;
    },
  }
});

Using a connector

The following example uses the connectHits connector.

JavaScript

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')
  })
]);

Handle search errors

If an error occurs, you can display a specific piece of content to help users return to the standard state. You can build a custom widget to handle errors. If you want to learn more about custom widgets, check out the guide.

JavaScript

search.addWidgets([
  {
    $$type: 'error-display',
    render({ status, error }) {
      if (status === '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 if users are online, and logging the error in your monitoring system.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Conditional display in InstantSearch.js

Handle searches without results

Display a message

Let users reset filters and facets

Handle empty queries

Using `transformItems`

Using a connector

Handle search errors

Making an error-handling widget

​Handle searches without results

​Display a message

​Let users reset filters and facets

​Handle empty queries

​Using transformItems

​Using a connector

​Handle search errors

​Making an error-handling widget

Handle searches without results

Display a message

Let users reset filters and facets

Handle empty queries

Using `transformItems`

Using a connector

Handle search errors

Making an error-handling widget