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.

Before you begin

This quickstart requires:

Basic React knowledge.
A React ≥ 16.8.0 app. If you don’t have a React app, use this CodeSandbox template.
An Algolia account. If you don’t have one, create a new account for free.
An Algolia with image, categories, name, brand, and price attributes. If you don’t have one, use a sample dataset and send it to Algolia.
algoliasearch and react-instantsearch installed.

Quickstart

In this quickstart, you’ll add an Algolia search interface to some starter code. The code:

Displays and formats a search box and results
Uses InstantSearch’s pre-built UI components (widgets) to filter results

Add a search box

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 search results

Display the results returned by Algolia using 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.

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

Screenshot of a search for 'magic mouse' showing Apple products under 'COMPUTERS and TABLETS'.

Highlight matches

It’s not always clear why one result ranks above another. To help make things more evident to users, you can highlight the parts of a result that match the .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.

Search box results with query highlighting in the quickstart app

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

Paginate your results

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

The browser 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

You can override any search parameters with Configure. This widget doesn’t render anything but instead instructs InstantSearch to send custom search parameters to Algolia.This update sets 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>
  );
}

Next steps

With this quickstart, you’ve got a solid starting point for building dynamic search interfaces. To enhance it:

Use your own data.
Load hits without pagination using InfiniteHits.
Search more than one index with Index.
Server-side render your app for increased performance.
Provide some more refinement widgets. For example:
- Menu to refine on a single value per attribute
- HierarchicalMenu to filter 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.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Get started with React InstantSearch

Before you begin

Quickstart

Next steps

See also

​Before you begin

​Quickstart

​Next steps

​See also

Before you begin

Quickstart

Next steps

See also