Conditional display

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

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:

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 useInstantSearch Hook to create a wrapper component:

React

function App(props) {
  return (
    <InstantSearch {...props}>
      <SearchBox />
      <NoResultsBoundary fallback={<NoResults />}>
        <Hits />
      </NoResultsBoundary>
    </InstantSearch>
  );
}

function NoResultsBoundary({ children, fallback }) {
  const { results } = useInstantSearch();

  // Skip the message for placeholder results before the first response.
  if (!results.__isArtificial && results.nbHits === 0) {
    return (
      <>
        {fallback}
        <div hidden>{children}</div>
      </>
    );
  }

  return children;
}

function NoResults() {
  const { indexUiState } = useInstantSearch();

  return (
    <div>
      <p>
        No results for <q>{indexUiState.query}</q>.
      </p>
    </div>
  );
}

You can pass anything to display results, including InfiniteHits or a custom component that uses the useHits Hook.

To prevent undesirable, additional search requests, see Show and hide widgets.

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.

React

function NoResults() {
  const { indexUiState } = useInstantSearch();

  return (
    <div>
      <p>
        No results for <q>{indexUiState.query}</q>.
      </p>
      <ClearRefinements excludedAttributes={[]} />
    </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 wrapper. This hides the results without preventing search requests.

React

function App(props) {
  return (
    <InstantSearch {...props}>
      <SearchBox />
      <EmptyQueryBoundary fallback={null}>
        <Hits />
      </EmptyQueryBoundary>
    </InstantSearch>
  );
}

function EmptyQueryBoundary({ children, fallback }) {
  const { indexUiState } = useInstantSearch();

  if (!indexUiState.query) {
    return (
      <>
        {fallback}
        <div hidden>{children}</div>
      </>
    );
  }

  return children;
}

Follow best practices for showing and hiding React InstantSearch widgets to prevent undesirable additional search requests.

Handle search errors

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

React

import React, { useEffect, useState } from "react";
import * as Toast from "@radix-ui/react-toast";
import { useInstantSearch } from "react-instantsearch";

function SearchErrorToast() {
  const { addMiddlewares } = useInstantSearch();
  const [error, setError] = useState(null);

  useEffect(() => {
    const middleware = ({ instantSearchInstance }) => {
      function handleError(searchError) {
        setError(searchError);
      }

      return {
        subscribe() {
          instantSearchInstance.addListener("error", handleError);
        },
        unsubscribe() {
          instantSearchInstance.removeListener("error", handleError);
        },
      };
    };

    return addMiddlewares(middleware);
  }, [addMiddlewares]);

  if (!error) {
    return null;
  }

  return (
    <Toast.Provider>
      <Toast.Root
        onOpenChange={(isOpen) => {
          if (!isOpen) {
            setError(null);
          }
        }}
      >
        <Toast.Title>{error.name}</Toast.Title>
        <Toast.Description>{error.message}</Toast.Description>
      </Toast.Root>

      <Toast.Viewport />
    </Toast.Provider>
  );
}

function App(props) {
  return (
    <InstantSearch {...props}>
      <SearchErrorToast />
      <SearchBox />
      <Hits />
    </InstantSearch>
  );
}

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Conditional display

Handle searches without results

Display a message

Let users reset filters and facets

Handle empty queries

Handle search errors

​Handle searches without results

​Display a message

​Let users reset filters and facets

​Handle empty queries

​Handle search errors

Handle searches without results

Display a message

Let users reset filters and facets

Handle empty queries

Handle search errors