Guides / Building Search UI

Getting started with 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.

On this page

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.

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

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

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

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.

Copy 
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 { liteClient as algoliasearch } from 'algoliasearch/lite';
-import { InstantSearch, SearchBox } from 'react-instantsearch';
+import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';

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

+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.

Hits without highlighting

Hits without highlighting

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.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

 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('YourApplicationID', 'YourSearchOnlyAPIKey');

 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>
   );
 }

Replace INDEX_NAME with the name of your index.

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

Results with highlighting

Results with highlighting

Send click and conversion events

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

Copy 
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
26
27
28
29
30
31
32

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

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

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>
  );
}

Replace INDEX_NAME with the name of your index.

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.

Copy 
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
26
27
28
29
30
31
32
33

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

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

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:

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

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

Use the <Pagination> widget to navigate the pages.

Copy 
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 { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
  Hits,
  Highlight,
  RefinementList,
+ Pagination,
} from 'react-instantsearch';

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

// ...

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

Replace INDEX_NAME with the name of your index.

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.

Copy 
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 { 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>
  );
}

Replace INDEX_NAME with the name of your index.

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:

Previous
Installation
Next
Click and conversion events
Did you find this page helpful?
React InstantSearch v7