How to install React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Install React InstantSearch as an npm package or include it in your app with a CDN link.

React InstantSearch is composed of two separate packages:

• react-instantsearch which exposes all UI widgets and re-exports all Hooks.
• react-instantsearch-core which only exposes all Hooks. You only need this package if you’re using React InstantSearch with React Native.

The code examples on this page use the React InstantSearch library with the algoliasearch/lite client, which is smaller but doesn’t support indexing your data. To perform indexing operations, import the regular algoliasearch client.

Install React InstantSearch as an npm package

If you’re using a package manager and a build tool, you can install React InstantSearch from npm:

1
2
3
npm install algoliasearch react-instantsearch
# or
yarn add algoliasearch react-instantsearch

1
2
3
npm install algoliasearch react-instantsearch-core
# or
yarn add algoliasearch react-instantsearch-core

Then in your app, import the module:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import React from 'react';
{/* Import React InstantSearch */}
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch';

{/*
  Initialize the search client

  If you're logged into the Algolia dashboard, the following values for
  YourApplicationID and YourSearchOnlyAPIKey are auto-selected from
  the currently selected Algolia application.
*/}
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App() {
  return (
    {/*
      Render the React InstantSearch wrapper.
      Replace INDEX_NAME with the name of your index.
    */}
    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
      {/* Add widgets here */}
    </InstantSearch>
  );
}

<InstantSearch> is the root React InstantSearch component. All widgets must be wrapped within it

In a production environment, secure your API keys as environment variables.

Include React InstantSearch with a CDN

If you don’t use a package manager and a build tool, you can include React InstantSearch directly from the jsDelivr CDN.

1
2
3
4
5
6
7
8
9
10
<script
  src="https://cdn.jsdelivr.net/npm/algoliasearch@4.24.0/dist/algoliasearch-lite.umd.js"
  integrity="sha256-b2n6oSgG4C1stMT/yc/ChGszs9EY/Mhs6oltEjQbFCQ="
  crossorigin="anonymous"
></script>
<script
  src="https://cdn.jsdelivr.net/npm/react-instantsearch@7.15.1/dist/umd/ReactInstantSearch.min.js"
  integrity="sha256-IUrmWeOY9GK0tl1yPfvsbJxjwj/LLtHPcKJbf9Spsjw="
  crossorigin="anonymous"
></script>

jsDelivr is a third-party CDN. Algolia can’t provide support for such third-party services.

You now have access to the ReactInstantSearch object on the global window object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const { InstantSearch } = ReactInstantSearch;

{/*
  Initialize the search client

  If you're logged into the Algolia dashboard, the following values for
  YourApplicationID and YourSearchOnlyAPIKey are auto-selected from
  the currently selected Algolia application.
*/}

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

function App() {
  return (
    {/*
      Render the React InstantSearch wrapper.
      Replace INDEX_NAME with the name of your index.
    */}
    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
      {/* Add widgets here */}
    </InstantSearch>
  );
}

<InstantSearch> is the root React InstantSearch component. All widgets must be wrapped within it.

In a production environment, you should secure your API keys as environment variables.

Send click and conversion events

Capturing real-time user interactions as events gives you actionable insights via click and conversion metrics, and they help you increase your customer engagement and conversions. Events are used to activate Algolia features and products like NeuralSearch, Dynamic Re-Ranking, Query Categorization, Recommend, and Personalization.

To send click and conversion events when users interact with your search UI, set the insights option to true.

TypeScript support

These packages ship with TypeScript types:

• react-instantsearch (v7)
• react-instantsearch-core (v7)

The following packages don’t ship with TypeScript types, but have DefinitelyTyped definitions you can use:

• react-instantsearch (v6)
• react-instantsearch-core (v6)
• react-instantsearch-dom (v6)
• react-instantsearch-native (v6)

If you have issues when using them, contact the DefinitelyTyped community.

The react-instantsearch-dom-maps package doesn’t ship with TypeScript types and doesn’t have any DefinitelyTyped definitions.

Browser support

Algolia supports the last two versions of the major browsers: Chrome, Edge, Firefox, Safari.

To support Internet Explorer 11 you need polyfills for: Array.prototype.find, Array.prototype.includes, Promise, Object.entries, and Object.assign.

The code samples in this documentation use a JavaScript syntax that isn’t natively supported by older browsers like Internet Explorer 11. If your site needs to support older browsers, use a tool like Babel to make your code work in the browsers you target.