API Reference / React InstantSearch / InstantSearch

InstantSearch

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

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

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

The main index in which to search.
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

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

<InstantSearch
  // ...
  searchClient={searchClient}
>
  {/* Widgets */}
</InstantSearch>
searchState
type: object
Optional

Injects a searchState to the InstantSearch component. Once this prop is provided, it switches to the controlled mode. Useful for URL Sync.
Copy 
1
2
3
4
5
6
7
8
9
10
11

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

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.
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
type: function
Optional

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.
Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  createURL={searchState => `?q=${searchState.query}`}
>
  {/* Widgets */}
</InstantSearch>
onSearchStateChange
type: function
Optional

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.
Copy 
1
2
3
4
5
6
7
8

<InstantSearch
  // ...
  onSearchStateChange={searchState => {
    // use the searchState
  }}
>
  {/* Widgets */}
</InstantSearch>
onSearchParameters
type: function
Optional

A function called every time search parameters are updated, usually by a widget. You can use it to collect search parameters as widgets update them. 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
type: boolean
Optional

Whether the cache needs to be cleared so that the front end is updated when a change occurs in the index.
Copy 
1
2
3
4
5
6

<InstantSearch
  // ...
  refresh
>
  {/* Widgets */}
</InstantSearch>
stalledSearchDelay
type: number
default: 200
Optional

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.
Copy 
1
2
3
4
5
6

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