InstantSearch / React / V6 / API reference

InstantSearch | React InstantSearch V6 (Deprecated)

Deprecated content
This documentation is for a deprecated version of React InstantSearch. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of React InstantSearch for up-to-date information.

Signature

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

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

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

import { liteClient as 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
Type: string

The main index in which to search.

Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  indexName="instant_search"
>
  {/* Widgets */}
</InstantSearch>

searchClient

Required
Type: object

Provides a search client to InstantSearch. Read the custom backend guidance on implementing a custom search client.

Copy 
1
2
3
4
5
6
7
8
9
10
11

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

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

searchState

Optional
Type: object

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

Copy 
1
2
3
4
5
6
7
8
9
10
11

<InstantSearch
  // ...
  searchState={{
    query: 'iphone',
    refinementList: {
      brand: ['Apple'],
    },
  }}
>
  {/* Widgets */}
</InstantSearch>

resultsState

Optional
Type: object

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

Copy 
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

Optional
Type: function

This function is called when InstantSearch creates links, which is helpful for URL syncing. The callback is called with the searchState. The example below creates a URL from the query for demonstration purposes only. You usually would serialize the full searchState to the URL.

Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  createURL={searchState => `?q=${searchState.query}`}
>
  {/* Widgets */}
</InstantSearch>

onSearchStateChange

Optional
Type: function

This function is called on every searchState change. You can alter the searchState used for the next search. Useful for URL sync.

Copy 
1
2
3
4
5
6
7
8

<InstantSearch
  // ...
  onSearchStateChange={searchState => {
    // use the searchState
  }}
>
  {/* Widgets */}
</InstantSearch>

onSearchParameters

Optional
Type: function

This function is called every time search parameters are updated, usually by a widget. Use it to collect search parameters as widgets update them, and this is what the library uses internally for server-side rendering.

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

let searchParameters = new algoliasearchHelper.SearchParameters({});
<InstantSearch
  // ...
  onSearchParameters={
  (getWidgetSearchParameters, context, props, searchState) => {
    searchParameters = getWidgetSearchParameters(
      searchParameters,
      props,
      searchState
    )
    // Use the new searchParameters
  }}
>
  {/* Widgets */}
</InstantSearch>

refresh

Optional
Type: boolean

Use this option to decide if you should clear the cache when the index changes (to update the frontend).

Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  refresh
>
  {/* Widgets */}
</InstantSearch>

stalledSearchDelay

Optional
Type: number

A time period (in ms) after which the search is considered to have stalled. This value impacts the prop isSearchStalled provided to the SearchBox.

Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  stalledSearchDelay={500}
>
  {/* Widgets */}
</InstantSearch>
Did you find this page helpful?