Skip to main content
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.
InstantSearch focuses on enhancing your frontend with primitives that you can combine to create unique search interfaces. InstantSearch supports server-side rendering and offers full routing capabilities.

Open CodeSandbox

Run and edit the What is React InstantSearch? example in CodeSandbox.
InstantSearch offers three levels of increasing control over your UI:
  1. Start with a predefined widget that you can configure and style with CSS.
  2. To change the render output of a widget, use Hooks to render what you want.
  3. To implement something that doesn’t exist, create a custom Hook.

​
Predefined widgets

The recommended way to use InstantSearch is with its predefined widgets such as SearchBox. InstantSearch includes a set of widgets that are most often used in search experiences. Widgets provide features and a rendered output. You can place them anywhere on your UI, configure them, and style them with CSS. For example, add the RefinementList` widget and ask it to show a list of brands, so your users can refine their search using those brands.
React
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, RefinementList } from "react-instantsearch";

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";
const indexName = "INDEX_NAME";

const searchClient = algoliasearch(appID, apiKey);

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName={indexName}>
      <RefinementList attribute="brand" />
    </InstantSearch>
  );
}

​
The InstantSearch wrapper

The InstantSearch wrapper communicates between your app and Algolia. This is where you add all the widgets. It accepts a search client and an name. Screenshot of a refinement list widget showing brand filters with checkboxes and count labels. Refinement list widget

​
CSS theme

The predefined widgets in React InstantSearch are compatible with the default CSS theme: Screenshot of a search results page with product cards, a refinement list, and pagination controls. Default theme preview For more information, see Style your widgets.
If you use Hooks and you want to use the default theme in your app, follow the markup from the predefined widgets and use the InstantSearch class names.

​
Use Hooks

Algolia’s predefined widgets, with their fixed behavior and output, may not fully meet your requirements. For example, you might want to use React InstantSearch with a component library like Material UI or render to a non-DOM target like React Native. To address these limitations, use Hooks to construct the UI you want: For more information, see Customize a React InstantSearch widget.

​
Example component

Here’s an example of a custom RefinementList component created with useRefinementList, and mounted in the InstantSearch provider. 
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch } from "react-instantsearch";
import { RefinementList } from "./RefinementList";

const searchClient = algoliasearch("undefined", "undefined");

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="instant_search">
      <RefinementList attribute="brand" />
    </InstantSearch>
  );
}

import { useRefinementList } from "react-instantsearch";

export function RefinementList(props) {
  // Retrieves the refinement `items` and the `refine` function to update the
  // refinement
  const { items, refine } = useRefinementList(props);

  return (
    <div className="ais-RefinementList">
      <ul className="ais-RefinementList-list">
        {items.map((item) => (
          <li
            key={item.value}
            className={cx(
              "ais-RefinementList-item",
              item.isRefined && "ais-RefinementList-item--selected",
            )}
          >
            <label className="ais-RefinementList-label">
              <input
                className="ais-RefinementList-checkbox"
                type="checkbox"
                value={item.value}
                checked={item.isRefined}
                onChange={() => refine(item.value)}
              />
              <span className="ais-RefinementList-labelText">{item.label}</span>
              <span className="ais-RefinementList-count">{item.count}</span>
            </label>
          </li>
        ))}
      </ul>
    </div>
  );
}

function cx(...classNames) {
  return classNames.filter(Boolean).join(" ");
}

​
Pass stable references

When you provide a function to Hooks, make sure to pass a stable reference to avoid rendering endlessly (for example, with useCallback). You don’t need to stabilize objects and arrays, because React reuses them between renders unless you create new ones.
React
import { liteClient as algoliasearch } from "algoliasearch/lite";
import React, { useCallback } from "react";
import { InstantSearch, useHits } from "react-instantsearch";

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";

const searchClient = algoliasearch(appID, apiKey);

function Search({ cartItems }) {
  const transformItems = useCallback(
    (items) =>
      items.map((item) => ({
        ...item,
        isInCart: Boolean(
          cartItems.find((cartItem) => cartItem.objectID === item.objectID),
        ),
      })),
    [cartItems],
  );
  const { hits } = useHits({ transformItems });

  return <>{/* Your JSX */}</>;
}

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

​
Custom Hooks

React InstantSearch works with all InstantSearch.js connectors: from Algolia, from the community, or even your own. To create a Hook:
  1. Create a connector.
  2. Use useConnector to turn the connector into a Hook:
import { useConnector } from "react-instantsearch";
import { connectMyWidget } from "./connectMyWidget";

export function useMyWidget(props) {
  return useConnector(connectMyWidget, props);
}

import { useMyWidget } from "./useMyWidget";

export function MyComponent(props) {
  const data = useMyWidget(props);

  // Render based on the data returned by the Hook
  return null;
}

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch } from "react-instantsearch";
import { MyComponent } from "./MyComponent";

const searchClient = algoliasearch("undefined", "undefined");

function App() {
  return (
    <InstantSearch searchClient={searchClient} indexName="instant_search">
      <MyComponent />
    </InstantSearch>
  );
}
You can now use your new Hook and component anywhere within InstantSearch.

​
Resources

Use the following links and resources to learn more.

​
See also

​
Join the community

Ask questions and find answers on those following platforms.
Last modified on May 7, 2026