API Reference / React InstantSearch Hooks / useInstantSearch()

Sep. 12, 2022

useInstantSearch()

Signature

const {
  indexUiState,
  setIndexUiState,
  uiState,
  setUiState,
  results,
  scopedResults
  refresh,
  use,
} = useInstantSearch()

Import

Copy

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

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-hooks-web';

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-hooks-web';

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
import { useInstantSearch } from 'react-instantsearch-hooks-web';

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-hooks-web';

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-hooks-web';

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-hooks-web';

function InsightsMiddleware(props) {
  const { use } = 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 use(middleware);
  }, [use, props]);

  return null;
}

Returns


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


            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.

use

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

Adds a middleware. It returns its own cleanup function.

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

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

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

  return null;
}

Did you find this page helpful?

useInstantSearch()

About this Hook

Examples

Returns

On this page