Get started with React InstantSearch

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.

React InstantSearch is a React library that lets you create a search results experience with Algolia. This tutorial generates code to:

Add a search box
Display and highlight search results
Add a filter to narrow down the results set
Paginate results
Apply search parameters.

Before you begin

This tutorial assumes you have React knowledge and an existing React ≥ 16.8.0 app. If you don’t have a React app, start with this CodeSandbox template. The tutorial also requires an installation of algoliasearch and react-instantsearch. The main UI component of a search experience is a search box. It’s often how users discover content in your app. React InstantSearch provides a SearchBox widget to display an Algolia search box.

React

// App.jsx
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, SearchBox } from "react-instantsearch";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

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

Replace INDEX_NAME with the name of your index.

If you type in the search box, you won’t see any results until you add a hits widget to display them.

Display results

When Algolia returns results, you want to list them in the UI. To do this, use the Hits widget.

App.jsx

 import { liteClient as algoliasearch } from 'algoliasearch/lite';
-import { InstantSearch, SearchBox } from 'react-instantsearch';
+import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';

 const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

+function Hit({ hit }) {
+  return (
+    <article>
+      <img src={hit.image} alt={hit.name} />
+      <p>{hit.categories[0]}</p>
+      <h1>{hit.name}</h1>
+      <p>${hit.price}</p>
+    </article>
+  );
+}

 function App() {
   return (
     <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
       <SearchBox />
+      <Hits hitComponent={Hit} />
     </InstantSearch>
   );
 }

Replace INDEX_NAME with the name of your index. Replace the image, categories, name, and price attributes with attributes that are in your index.

The Hits widget updates whenever you type a character in the search box.

Sometimes it’s hard to understand why one hit ranks higher than another. To help make things more evident to users, you can highlight the parts of a result that match the query.

Highlight matches

Algolia supports highlighting and returns the highlighted parts of a result in the response. Use the Highlight widget to highlight matches in each attribute.

App.jsx

 import { liteClient as algoliasearch } from 'algoliasearch/lite';
-import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';
+import {
+  InstantSearch,
+  SearchBox,
+  Hits,
+  Highlight,
+} from 'react-instantsearch';

 const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

 function Hit({ hit }) {
   return (
     <article>
       <img src={hit.image} alt={hit.name} />
       <p>{hit.categories[0]}</p>
-      <h1>{hit.name}</h1>
+      <h1>
+        <Highlight attribute="name" hit={hit} />
+      </h1>
       <p>${hit.price}</p>
     </article>
   );
 }

When users type a query, the UI highlights matches in each search result.

Send click and conversion events

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

App.jsx

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
  Hits,
  Highlight,
} from 'react-instantsearch';

const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

function Hit({ hit }) {
  return (
    <article>
      <img src={hit.image} alt={hit.name} />
      <p>{hit.categories[0]}</p>
      <h1>
        <Highlight attribute="name" hit={hit} />
      </h1>
      <p>${hit.price}</p>
    </article>
  );
}

function App() {
  return (
-     <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
+     <InstantSearch searchClient={searchClient} indexName="INDEX_NAME" insights>
      <SearchBox />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

Add a filter

A search box is a great way to refine a search experience, but sometimes users need to narrow down the results to find what they’re looking for in a specific category. Use RefinementList to filter items based on attributes such as brand, size, or color.

App.jsx

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
  Hits,
  Highlight,
+ RefinementList,
} from 'react-instantsearch';

const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

function Hit({ hit }) {
  return (
    <article>
      <img src={hit.image} alt={hit.name} />
      <p>{hit.categories[0]}</p>
      <h1>
        <Highlight attribute="name" hit={hit} />
      </h1>
      <p>${hit.price}</p>
    </article>
  );
}

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME" insights>
      <SearchBox />
+     <RefinementList attribute="brand" />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

Replace INDEX_NAME with the name of your index. Replace the brand attributes with one of your index’s faceting attributes.

Refinement lists let you refine multiple values. React InstantSearch provides several refinement widgets with specialized behaviors:

Menu to refine on a single value per attribute
HierarchicalMenu to filter down a hierarchy of categories
ToggleRefinement to filter on and off on a given attribute value

If you have several refinement widgets, use CurrentRefinements to display the active filters and let users remove them individually.

Paginate your results

The app only shows 20 hits but Algolia returns more results.

The Network tab shows the number of hits and number of pages

Use the Pagination widget to navigate the pages.

App.jsx

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
  Hits,
  Highlight,
  RefinementList,
+ Pagination,
} from 'react-instantsearch';

const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

// ...

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME" insights>
      <SearchBox />
      <RefinementList attribute="brand" />
      <Hits hitComponent={Hit} />
+     <Pagination />
    </InstantSearch>
  );
}

Configure search parameters

Algolia returns 20 hits by default but you can override any search parameters with Configure. This widget doesn’t render anything but still instructs InstantSearch to send custom search parameters to Algolia. You can render the Configure widget in your app, specifying 40 hits per page.

App.jsx

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
  Hits,
  Highlight,
  RefinementList,
  Pagination,
+ Configure,
} from 'react-instantsearch';

// ...

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME" insights>
+     <Configure hitsPerPage={40} />
      <SearchBox />
      <RefinementList attribute="brand" />
      <Hits hitComponent={Hit} />
      <Pagination />
    </InstantSearch>
  );
}

You can pass any search parameters to Configure, even reactive props coming from the React state but you shouldn’t overuse Configure. If you need to set a search parameter after user interactions, consider using a refinement widget.

Next steps

With this tutorial, you’ve got a solid starting point for building dynamic search interfaces. Improve the app by:

Loading hits without pagination using InfiniteHits.
Searching in multiple indices with Index.
Server-side rendering your application for increased performance.
Checking the API reference to discover more widgets and Hooks.

Guides

​Before you begin

​Add a search box

​Display results

​Highlight matches

​Send click and conversion events

​Add a filter

​Paginate your results

​Configure search parameters

​Next steps

Before you begin

Add a search box

Display results

Highlight matches

Send click and conversion events

Add a filter

Paginate your results

Configure search parameters

Next steps