useInstantSearch

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.

Signature

  const {
    indexUiState,
    setIndexUiState,
    uiState,
    setUiState,
    indexRenderState,
    renderState,
    results,
    scopedResults
    refresh,
    status,
    error,
    addMiddlewares,
  } = useInstantSearch({
    catchError
  })

Import

JavaScript

import { useInstantSearch } from "react-instantsearch";

About this Hook

A React Hook that lets you access the InstantSearch API and interact with its state. Use useInstantSearch to access and update UI state, retrieve search results, refresh the search, and add middleware. Call this Hook from a component inside InstantSearch.

Examples

import {
  InstantSearch,
  RefinementList,
  useInstantSearch,
} from "react-instantsearch";

function Discounts() {
  const { indexUiState, setIndexUiState } = useInstantSearch();
  const disabled = indexUiState.refinementList?.discounts?.includes("-50% off");

  return (
    <button
      type="button"
      disabled={disabled}
      onClick={() => {
        setIndexUiState((prevIndexUiState) => ({
          ...prevIndexUiState,
          refinementList: {
            ...prevIndexUiState.refinementList,
            discounts: ["-50% off", "free shipping"],
          },
        }));
      }}
    >
      Show discounts
    </button>
  );
}

function App({ searchClient }) {
  return (
    <InstantSearch searchClient={searchClient} indexName="instant_search">
      <Discounts />
      <RefinementList attribute="discounts" />
    </InstantSearch>
  );
}

import {
  InstantSearch,
  Hits,
  SearchBox,
  useInstantSearch,
} from "react-instantsearch";

function App({ searchClient }) {
  return (
    <InstantSearch searchClient={searchClient} indexName="instant_search">
      <SearchBox />
      <NoResultsBoundary fallback={<NoResults />}>
        <Hits />
      </NoResultsBoundary>
    </InstantSearch>
  );
}

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

  if (!results.__isArtificial && results.nbHits === 0) {
    return fallback;
  }

  return children;
}

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

  return (
    <div>
      <p>No results.</p>

      <button
        onClick={() => {
          setUiState({});
        }}
      >
        Reset search
      </button>
    </div>
  );
}

import { useInstantSearch } from "react-instantsearch";

function Refine() {
  const { indexRenderState } = useInstantSearch();

  return (
    <button
      onClick={() => {
        indexRenderState.refinementList.brand.refine("apple");
      }}
    >
      Toggle "apple"
    </button>
  );
}

import { useInstantSearch } from "react-instantsearch";

function Refine() {
  const { renderState } = useInstantSearch();

  return (
    <button
      onClick={() => {
        renderState.instant_search.refinementList.brand.refine("apple");
      }}
    >
      Toggle "apple"
    </button>
  );
}

import { useInstantSearch } from "react-instantsearch";

function Stats() {
  const { results } = useInstantSearch();

  return (
    <div>
      {results.nbHits} results found for the query "{results.query}".
    </div>
  );
}

import { useInstantSearch } from "react-instantsearch";

function Stats() {
  const { scopedResults } = useInstantSearch();

  const totalNbHits = scopedResults.reduce(
    (acc, { results }) => acc + results.nbHits,
    0,
  );

  return <div>{totalNbHits} results found across all indices.</div>;
}

import { useInstantSearch } from "react-instantsearch";

function Refresh() {
  const { refresh } = useInstantSearch();

  return <button onClick={refresh}>Refresh</button>;
}

import { createInsightsMiddleware } from "instantsearch.js/es/middlewares";
import { useInstantSearch } from "react-instantsearch";

function InsightsMiddleware(props) {
  const { addMiddlewares } = useInstantSearch();

  // The Insights middleware is added in a layout effect because it mounts
  // a <Configure> widget. Widgets must be added in layout effects to minimize
  // the number of network requests.
  useLayoutEffect(() => {
    const middleware = createInsightsMiddleware(props);

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

  return null;
}

import { useInstantSearch } from "react-instantsearch";

function Status() {
  const { status } = useInstantSearch();

  if (status === "loading" || status === "stalled") {
    return <>Loading...</>;
  }
}

import { useInstantSearch } from "react-instantsearch";

function Error() {
  const { error } = useInstantSearch({ catchError: true });

  if (error) {
    return <>Search error: {error.message}</>;
  }
}

Parameters

boolean

default:false

If true, InstantSearch catches errors during the search lifecycle and exposes them through the error property. If you handle these errors elsewhere, set catchError to false.

Returns

IndexUiState

The uiState of the parent .

(indexUiState: IndexUiState) => void | ((prevIndexUiState: IndexUiState) => IndexUiState) => void

Updates the uiState of the parent index..Accepts a new index UI state object or a function that receives the current index UI state and returns the next index UI state.

Mount the widget that manages the UI state you update. For example, mount a RefinementList widget, or an equivalent virtual widget, for changes to refinementList to take effect.

setIndexUiState((prevIndexUiState) => ({
  ...prevIndexUiState,
  refinementList: {
    ...prevIndexUiState.refinementList,
    discounts: ["-50% off", "free shipping"],
  },
}));

setIndexUiState({
  refinementList: {
    discounts: ["-50% off", "free shipping"],
  },
});

SearchResults

The search results.

UiState

The uiState of the search interface.Each property maps an index identifier to that index’s UI state. By default, the identifier is the index name.

(uiState: UiState) => void | ((prevUiState: UiState) => UiState) => void

Function to update the uiState of the search.This function either takes a new uiState object, or a function that exposes the current uiState object and returns a new one.

Mount the widget that manages the UI state you update. For example, mount a RefinementList widget, or an equivalent virtual widget, for changes to refinementList to take effect.

const indexName = 'instant_search';
setIndexUiState((prevUiState) => ({
  ...prevUiState,
  [indexName]: {
    ...prevUiState[indexName].refinementList,
    refinementList: {
      ...prevUiState[indexName].refinementList,
      discounts: ['-50% off', 'free shipping'],
    },
  },
}));

const indexName = "instant_search";
setIndexUiState({
  [indexName]: {
    refinementList: {
      discounts: ["-50% off", "free shipping"],
    },
  },
});

ScopedResult[]

An array with the results of the index, as well as the results of all adjacent Index widgets.

TypeScript

type ScopedResult = {
  indexId: string;
  results: SearchResults;
};

IndexRenderState

The renderState of the parent index.

RenderState

since: v7.2.0

The renderState of the search.

() => void

Clears the search client’s cache and performs a new search.This is useful to update the results once an indexing operation has finished.

(...middlewares: Middleware[]) => () => void

Adds one or more middleware functions to InstantSearch. Returns a cleanup function that removes them.

JavaScript

import { myMiddleware } from "./myMiddleware";

function MyMiddleware() {
  const { addMiddlewares } = useInstantSearch();

  useEffect(() => {
    return addMiddlewares(myMiddleware);
  }, [addMiddlewares]);

  return null;
}

idle | loading | stalled | error

The status of the search happening.Possible values are:

'idle': no search request is in progress.
'loading': a search request is in progress. Use this status to provide immediate feedback after an action. For loading indicators, use 'stalled' instead.
'stalled': the search has exceeded stalledSearchDelay.
'error': the search failed. The error property contains the search error.

Error | undefined

The error that occurred during the search. This is only valid when status is 'error'.

​Import

​About this Hook

​Examples

​Parameters

​Returns

Import

About this Hook

Examples

Parameters

Returns