Instantsearch / React / V5 / API Reference

InstantSearch | React InstantSearch V5 (Deprecated)

This version of React InstantSearch has been deprecated in favor of the latest version of React InstantSearch.

Signature

Widget signature
<InstantSearch
  indexName={string}
  searchClient={object}
  // Optional parameters
  searchState={object}
  resultsState={object}
  createURL={function}
  onSearchStateChange={function}
  refresh={boolean}
  stalledSearchDelay={number}
  root={object}
/>

About this widget

InstantSearch is the root component of all React InstantSearch implementations. It provides to all the connected components (or widgets) a way to interact with the searchState.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch-dom';

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

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

Props

indexName

required: true
type: string

The main index in which to search.

1
2
3
4
5
6
<InstantSearch
  // ...
  indexName="instant_search"
>
  {/* Widgets */}
</InstantSearch>

searchClient

required: true
type: object

Provides a search client to InstantSearch. To implement a custom search client, take a look at a the custom back-end guide.

1
2
3
4
5
6
7
8
9
10
11
const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

<InstantSearch
  // ...
  searchClient={searchClient}
>
  {/* Widgets */}
</InstantSearch>

searchState

required: false
type: object

Injects a searchState to the InstantSearch component. Once this prop is provided, it switches to the controlled mode. Useful for URL Sync.

1
2
3
4
5
6
7
8
9
10
11
<InstantSearch
  // ...
  searchState={{
    query: 'iphone',
    refinementList: {
      brand: ['Apple'],
    },
  }}
>
  {/* Widgets */}
</InstantSearch>

resultsState

required: false
type: object

Injects the results that are used at first rendering. Those results are found by using the findResultsStatefunction. This is mostly useful for server-side rendering.

1
2
3
4
5
6
7
8
9
10
const resultsState = {
  // Object created on the server with `findResultsState`
};

<InstantSearch
  // ...
  resultsState={resultsState}
>
  {/* Widgets */}
</InstantSearch>

createURL

required: false
type: function

This function is called when InstantSearch has to create the links, useful for URL Sync. The callback is called with the searchState. The example below only creates a URL from the query for demonstration purposes. For most cases, you have to serialize the full searchState to the URL.

1
2
3
4
5
6
<InstantSearch
  // ...
  createURL={searchState => `?q=${searchState.query}`}
>
  {/* Widgets */}
</InstantSearch>

onSearchStateChange

required: false
type: function

A function called every time a state change happens. The callback is called with the searchState. You can alter the searchState used for the next search. Useful for URL Sync.

1
2
3
4
5
6
7
8
<InstantSearch
  // ...
  onSearchStateChange={searchState => {
    // use the searchState
  }}
>
  {/* Widgets */}
</InstantSearch>

refresh

required: false
type: boolean

Whether the cache needs to be cleared so that the front end is updated when a change occurs in the index.

1
2
3
4
5
6
<InstantSearch
  // ...
  refresh
>
  {/* Widgets */}
</InstantSearch>

stalledSearchDelay

required: false
type: number

The amount of time before considering that the search is stalled. This value impacts the prop isSearchStalled provided to the SearchBox. The time is expressed in milliseconds.

1
2
3
4
5
6
<InstantSearch
  // ...
  stalledSearchDelay={500}
>
  {/* Widgets */}
</InstantSearch>

root

required: false
type: object

Updates the element that is created by InstantSearch. You can specify which type of element you want along with its props. This is particularly useful for React Native to override the style of the root element.

1
2
3
4
5
6
7
8
9
10
11
12
13
<InstantSearch
  // ...
  root={{
    Root: 'section',
    props: {
      style: {
        display: 'flex',
      },
    },
  }}
>
  {/* Widgets */}
</InstantSearch>

Did you find this page helpful?