API Reference / React InstantSearch Hooks / <InstantSearch>

<InstantSearch>

Signature 
<InstantSearch
  indexName={string}
  searchClient={object}
  // Optional props
  initialUiState={object}
  onStateChange={function}
  stalledSearchDelay={number}
  routing={boolean | object}
/>
Import
Copy 
1

import { InstantSearch } from 'react-instantsearch-hooks-web';
See code examples

About this widget

<InstantSearch> is the root provider component of all widgets and Hooks.

To get you started with React InstantSearch Hooks, you need two parameters:

  • indexName: the main index you need to use for your new search UI
  • searchClient: the search client to plug to React InstantSearch Hooks

The search client provided by Algolia needs an appId and an apiKey. You can find those parameters in your Algolia dashboard.

To get up and running with React InstantSearch Hooks, have a look at the getting started guide.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      {/* Widgets */}
    </InstantSearch>
  );
}

Props

indexName
type: string
Required

The main index to search into.
Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  indexName="instant_search"
>
  {/* Widgets */}
</InstantSearch>
searchClient
type: object
Required

Provides a search client to <InstantSearch>. To implement a custom search client, take a look at a the custom back-end guide.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

function App() {
  return (
    <InstantSearch
      // ...
      searchClient={searchClient}
    >
      {/* Widgets */}
    </InstantSearch>
  );
}
initialUiState
type: object

Provides an initial state to your React InstantSearch widgets using InstantSearch.js’ uiState. To provide an initial state, you must add the corresponding widgets to your implementation.
Copy 
1
2
3
4
5
6
7
8
9
10
11

<InstantSearch
  // ...
  initialUiState={{
    indexName: {
      query: 'phone',
      page: 5,
    },
  }}
>
  {/* Widgets */}
</InstantSearch>
onStateChange
type: function

Triggers when the state changes.

When using this option, the instance becomes controlled. This means that you become responsible for updating the UI state with setUiState.

This is useful to perform custom logic whenever the state changes.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const onStateChange = ({ uiState, setUiState }) => {
  // Custom logic
  setUiState(uiState);
};

function App() {
  return (
    <InstantSearch
      // ...
      onStateChange={onStateChange}
    >
      {/* Widgets */}
    </InstantSearch>
  );
}
stalledSearchDelay
type: number
default: 200

Defines a time period after which a search is considered stalled. You can find more information in the slow network guide.
Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  stalledSearchDelay={500}
>
  {/* Widgets */}
</InstantSearch>
routing
type: boolean | object

The router configuration used to save the UI state into the URL, or any client-side persistence. You can find more information in the routing guide.
Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  routing={true}
>
  {/* Widgets */}
</InstantSearch>
Did you find this page helpful?
React InstantSearch Hooks v6