Skip to main content
This guide describes what to do when there are no results, when there’s no query, or when there are errors. Sometimes, though, users may not get any hits if their device can’t access the network or the network connection is slow. If you want to feature content in your search results based on a set of conditions, you can use Algolia Rules to:
To learn how to suppress InstantSearch’s initial search query, check out the conditional requests guide.

​
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, 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.

​
Let users reset filters and facets

If users apply too many filters, they may not find any results. You should 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>`,
    },
  }),
]);

​
Handling empty queries

By default, InstantSearch 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 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')
  })
]);

​
Handling errors

If an error occurs, you can display a specific piece of content to help users 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.
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.
⌘I