useInstantSearch

React Hook for accessing state and results of your React InstantSearch apps.

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.

This is useful to access and update the UI state, access the search results, refresh the search, or use middleware.

Hooks must be used inside the <InstantSearch> component.

Examples

indexUiState

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

Parameters

catchError · boolean · default: false

If true, errors thrown by InstantSearch are handled by InstantSearch and are available in the error property. Set catchError to false if you want to handle these errors elsewhere.

Returns

indexUiState · IndexUiState

The uiState of the parent index.

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

Updates the uiState of the parent index.

This function either takes a new index uiState object, or a function that exposes the current index uiState object and returns a new one.

Make sure to mount the widget responsible for the UI state. For example, mount a <RefinementList> (or a virtual widget) for the refinementList UI state to take effect.

Function

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

results · SearchResults

The search results.

uiState · UiState

The uiState of the search.

This is an object with each index name as key and the current UI state for that index as value.

setUiState · (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.

Make sure to mount the widget responsible for the UI state. For example, mount a <RefinementList> (or a virtual widget) for the refinementList UI state to take effect.

Function

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

scopedResults · 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 · IndexRenderState

The renderState of the parent index.

renderState · RenderState · since: v7.2.0

The renderState of the search.

refresh · () => 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.

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

Adds a middleware. It returns its own cleanup function.

JavaScript

import { myMiddleware } from "./myMiddleware";

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

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

  return null;
}

status · idle | loading | stalled | error

The status of the search happening.

Possible values are:

• 'idle'. There currently is no search happening.
• 'loading'. The search is loading. This can be used for immediate feedback of an action, but for loading indicators, use 'stalled' instead.
• 'stalled'. The search is stalled. This gets triggered after stalledSearchDelay expires.
• 'error'. The search failed. The error is available in the error property.

error · Error | undefined

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