Get started with React InstantSearch

Use React InstantSearch to create a dynamic, filterable search UI.

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

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

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

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

   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.

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

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

6. Paginate your results

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

   

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

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

See also

• What is InstantSearch?
• InstantSearch widgets
• Send click and conversion events