React InstantSearch

Common errors

• TypeError: Cannot read properties of undefined (reading 'init') OR searchClient is not a function

  cause The `searchClient` prop passed to `<InstantSearch>` is either undefined, null, or not a valid Algolia search client instance.
  fix Verify that `algoliasearch` is correctly imported (using `liteClient` for browser) and initialized with valid App ID and Search API Key. Ensure the `searchClient` variable is defined before being passed as a prop.

• Error: No index found. Please make sure to pass an 'indexName' prop to the <InstantSearch> component.

  cause The `indexName` prop is missing or empty on the `<InstantSearch>` component.
  fix Add the `indexName` prop to your `<InstantSearch>` component, specifying the name of your Algolia index (e.g., `<InstantSearch indexName="your_index_name" searchClient={searchClient}>`).

• Error: Hooks can only be called inside of the body of a function component.

  cause This error typically indicates that React InstantSearch components are being used with an outdated React version (pre-16.8) or outside of a functional React component context.
  fix Upgrade your `react` and `react-dom` packages to version 16.8.0 or higher. Ensure all React InstantSearch components are rendered within a functional React component.

Warnings

• breaking React InstantSearch versions 6 and above are designed for ESM environments. Using CommonJS `require()` or older build setups may lead to issues.
  Fix: Ensure your project is configured for ES Modules (e.g., "type": "module" in `package.json` or using a modern bundler like Webpack/Vite with appropriate configuration). Prefer `import` statements over `require()`.
• breaking React InstantSearch relies on React Hooks, introduced in React 16.8. Older versions of React will not be compatible.
  Fix: Upgrade your `react` and `react-dom` peer dependencies to version 16.8.0 or newer. Check your `package.json` and install the latest compatible versions.
• gotcha React InstantSearch components provide functionality but minimal styling by default. You need to import a theme or provide your own CSS.
  Fix: To get basic styling, import one of the provided themes, e.g., `import 'instantsearch.css/themes/algolia.css';` in your entry file. For full control, write custom CSS to style the generated DOM elements.
• gotcha Using the full `algoliasearch` client bundle (`import algoliasearch from 'algoliasearch';`) in a browser environment can unnecessarily increase your bundle size.
  Fix: Always use the `liteClient` named import from `algoliasearch/lite` for browser-based applications: `import { liteClient as algoliasearch } from 'algoliasearch/lite';`.

Install

• npm install react-instantsearch npm
• yarn add react-instantsearch yarn
• pnpm add react-instantsearch pnpm

Imports

• InstantSearch
  wrong:

  const InstantSearch = require('react-instantsearch');

  correct:

  import { InstantSearch } from 'react-instantsearch';

  This is the primary wrapper component for your search interface. CommonJS `require()` is not recommended for modern React projects and may cause issues.
• SearchBox
  wrong:

  import SearchBox from 'react-instantsearch/lib/SearchBox';

  correct:

  import { SearchBox } from 'react-instantsearch';

  One of many pre-built UI widgets. All UI widgets are named exports from the main package.
• Hits
  wrong:

  import { connectHits } from 'react-instantsearch/lib/connectors';

  correct:

  import { Hits } from 'react-instantsearch';

  The Hits component displays search results. While connectors exist for advanced use cases, the component itself is a named export.
• algoliasearch client
  wrong:

  import algoliasearch from 'algoliasearch';

  correct:

  import { liteClient as algoliasearch } from 'algoliasearch/lite';

  Use the `liteClient` named export from `algoliasearch/lite` to get a smaller bundle size suitable for client-side applications. Alias it to `algoliasearch` for consistency.

Quickstart

This quickstart demonstrates setting up a basic instant search interface with a search box and result list, connecting to an Algolia index.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';
import 'instantsearch.css/themes/algolia.css'; // Optional: for basic styling

// Replace with your Algolia App ID and Search API Key
const searchClient = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID ?? 'latency',
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY ?? '6be0576ff61c053d5f9a3225e2a90f76'
);

const App = () => (
  <InstantSearch indexName="bestbuy" searchClient={searchClient}>
    <h1>React InstantSearch Example</h1>
    <SearchBox placeholder="Search products..." />
    <Hits />
  </InstantSearch>
);

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);