UI libraries / React InstantSearch / Widgets

Dec. 04, 2023

useInstantSearch()

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature

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

Import

Copy

1
import { useInstantSearch } from 'react-instantsearch';

See code examples

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 middlewares.

Examples

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { useInstantSearch } from 'react-instantsearch';

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { useInstantSearch } from 'react-instantsearch';

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

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

1
2
3
4
5
6
7
8
9
10
11
import { useInstantSearch } from 'react-instantsearch';

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

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

1
2
3
4
5
6
7
8
9
10
11
12
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>;
}

1
2
3
4
5
6
7
import { useInstantSearch } from 'react-instantsearch';

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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;
}

1
2
3
4
5
6
7
8
9
import { useInstantSearch } from 'react-instantsearch';

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

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

1
2
3
4
5
6
7
8
9
import { useInstantSearch } from 'react-instantsearch';

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

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

Parameters

Parameter	Description
`catchError`	type: 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

Parameter Description


            indexUiState

type: IndexUiState

The uiState of the parent index.


            setIndexUiState

type: (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.

Copy

1
2
3
4
5
6
7
setIndexUiState((prevIndexUiState) => ({
  ...prevIndexUiState,
  refinementList: {
    ...prevIndexUiState.refinementList,
    discounts: ['-50% off', 'free shipping'],
  },
}));


            results

type: SearchResults

The search results.


            uiState

type: 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

type: (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.

Copy

1
2
3
4
5
6
7
8
9
10
11
const indexName = 'instant_search';
setIndexUiState((prevUiState) => ({
  ...prevUiState,
  [indexName]: {
    ...prevUiState[indexName].refinementList,
    refinementList: {
      ...prevUiState[indexName].refinementList,
      discounts: ['-50% off', 'free shipping'],
    },
  },
}));

1
2
3
4
5
6
7
8
const indexName = 'instant_search';
setIndexUiState({
  [indexName]: {
    refinementList: {
      discounts: ['-50% off', 'free shipping'],
    },
  },
});


            scopedResults

type: ScopedResult[]

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

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


            indexRenderState

type: IndexRenderState

The renderState of the parent index.


            renderState

since: v7.2.0

type: RenderState

The renderState of the search.


            refresh

type: () => 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

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

Adds a middleware. It returns its own cleanup function.

Copy
import { myMiddleware } from './myMiddleware';

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

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

  return null;
}


            status

type: "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

type: Error | undefined

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

Did you find this page helpful?

useInstantSearch()

About this Hook

Examples

Parameters

Returns

On this page