Registry / web-framework / react-instantsearch

react-instantsearch

library7.29.0jsnpmunverified

React InstantSearch is an open-source React library developed by Algolia, designed to help developers quickly create fast, dynamic search user interfaces. It leverages Algolia's powerful search API to deliver an instant search experience, adhering to modern React principles for component-based development. The current stable version is 7.29.0, with releases occurring regularly, typically monthly, as seen by the March 2026 update. Key differentiators include its highly customizable component architecture, seamless integration with the Algolia ecosystem, and a focus on best practices for search UI design. It's part of the broader InstantSearch family, offering similar experiences for other frameworks like Vue and vanilla JavaScript. For environments without DOM access, such as React Native, `react-instantsearch-core` is the appropriate alternative.

web-framework http-networking data

npm install react-instantsearch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-INSTANTSEARC

react-instantsearch

web-frameworkjavascriptv7.29.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

InstantSearch

✓ import { InstantSearch } from 'react-instantsearch';

✗ const InstantSearch = require('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

✓ import { SearchBox } from 'react-instantsearch';

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

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

Hits

✓ import { Hits } from 'react-instantsearch';

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

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

algoliasearch client

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

✗ import algoliasearch from 'algoliasearch';

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.

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

Debug

Known issues

breakingReact 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()`.

affects: >=6.0.0

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

affects: <16.8.0

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

affects: All

gotchaUsing 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';`.

affects: All

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

7.29.0latest on npm

Audit

Dependencies

algoliasearchrequiredRequired to communicate with Algolia's search API.

reactrequiredPeer dependency for React components.

react-domrequiredPeer dependency for rendering React components to the DOM.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/algolia/instantsearch ↗

packagehttps://www.npmjs.com/package/react-instantsearch ↗

homepagehttps://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/ ↗