InstantSearch

Root component for React InstantSearch apps.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<InstantSearch
  indexName={string}
  searchClient={object}
  // Optional props
  initialUiState={object}
  onStateChange={function}
  stalledSearchDelay={number}
  routing={boolean | object}
  insights={boolean | object}
  future={{
    preserveSharedStateOnUnmount: boolean,
    persistHierarchicalRootCount: boolean,
  }}
/>

Import

JavaScript

import { InstantSearch } from "react-instantsearch";

About this widget

<InstantSearch> is the root wrapper component for all widgets and Hooks. It takes two parameters:

• indexName. Your main search index
• searchClient. The search client for React InstantSearch. The search client needs an appId and an apiKey, which you can find in the Algolia dashboard.

See also: Get started with React InstantSearch

Middleware

React InstantSearch provides middleware to help you connect to other systems:

• Insights. Use the insights middleware to send click and conversion events
• Generic. With the middleware API, you can inject logic into React InstantSearch. For example, to send events to Google Analytics.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch } from "react-instantsearch";

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

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

Props

indexName · string · required

The main index in which to search.

JavaScript

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

searchClient · object · required

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

The client uses a cache to avoid unnecessary search operations, so you should use a stable reference to the same search client instance rather than creating a new one on each render. Avoid inlining the function call to algoliasearch as the prop value, and consider instantiating the client outside your React components.

JavaScript

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

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

initialUiState · object

Provides an initial state to your React InstantSearch widgets using the ui-state object from InstantSearch.js.

Since this sets the initial state for your UI, you need to include the corresponding widgets in your app. For example, page: 5 as initial state only has an effect if you include the pagination widget as well.

Replace YourIndexName with the name of your Algolia index.

JavaScript

<InstantSearch
  // ...
  initialUiState={{
    YourIndexName: {
      // Sets the initial query for the SearchBox widget
      query: "phone",
      // Sets the initial page number for the Pagination widget
      page: 5,
    },
  }}
>
  {/* Widgets */}
</InstantSearch>;

onStateChange · function

Triggered when the state changes. This can be helpful for performing custom logic on a state change.

When using onStateChange, the instance is under your control. You’re responsible for updating the UI state (with setUiState).

JavaScript

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

function App() {
  return (
    <InstantSearch
      // ...
      onStateChange={onStateChange}
    >
      {/* Widgets */}
    </InstantSearch>
  );
}

stalledSearchDelay · number · default: 200

A time period (in ms) after which the search is considered to have stalled. Read the slow network guide for more information.

JavaScript

<InstantSearch
  // ...
  stalledSearchDelay={500}
>
  {/* Widgets */}
</InstantSearch>;

routing · boolean | object · default: false

The router configuration used to save the UI state into the URL or any client-side persistence.

Show routing props

routing.router · object

This object stores the UI state. By default, it uses an instance of the history router with its default parameters.

Show router props

router.onUpdate · function

Adds an event listener that makes InstantSearch aware of external changes to the storage medium (such as the URL). Typically you’ll set up a listener for popstate, which triggers a callback with the current routeState.

router.read · function

Reads the routing storage and returns a routeState object.

router.write · function

Writes the routeState object into the routing storage.

router.createURL · function

Transforms the routeState object into a URL. It receives an object and returns a string (which may be empty).

router.dispose · function

Cleans up all event listeners.

routing.stateMapping · object

Transforms the uiState into the object saved by the router. The default value is provided by simple.

Show stateMapping props

stateMapping.stateToRoute · function

Transforms a ui-state representation into a routeState object. It receives an object that contains the UI state of all the widgets on the page. It can return any object that is readable by routeToState.

stateMapping.routeToState · function

Transforms routeState into a ui-state representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.

For more information, see Sync your URLs.

You can’t use initialUiState with routing as the two options override each other.

• Use initialUiState for simple and static use cases
• Use routing for anything complex or dynamic.

JavaScript

<InstantSearch
  // ...
  routing={true}
>
  {/* Widgets */}
</InstantSearch>;

insights · boolean | InsightsProps · default: false

Enables the Insights middleware and loads the search-insights library (if not already loaded). The Insights middleware sends view and click events automatically, and lets you set up your own click and conversion events.

To use this option with an object, refer to the Insights middleware options.

boolean

<InstantSearch
  // ...
  insights={true}
>
  {/* Widgets */}
</InstantSearch>;

future · object

Test new InstantSearch features without affecting others.

Show future props

future.preserveSharedStateOnUnmount · boolean · default: false · since: v7.2.0

Changes the way dispose is used in the InstantSearch lifecycle.

• If false (the default), each widget unmounting will also remove its state, even if multiple widgets read that UI state.
• If true, each widget unmounting will only remove its state if it’s the last of its type. This lets you to dynamically add and remove widgets without losing their state.

JavaScript

<InstantSearch
  // ...
  future={{
    preserveSharedStateOnUnmount: true,
  }}
>
  {/* Widgets */}
</InstantSearch>;

future.persistHierarchicalRootCount · boolean · default: false · since: v7.4.1

Whether to display a constant facet value count at the root of a hierarchical menu with active refinements.

If false (default), the facet value count at the root level shows the facet value count of the refined (child) facet’s parent.

If true, the facet value count at the root level shows the sum of the facet value counts of all its children, with or without refined children.

JavaScript

<InstantSearch
  // ...
  future={{
    persistHierarchicalRootCount: true,
  }}
>
  {/* Widgets */}
</InstantSearch>;