{"id":11732,"library":"react-instantsearch","title":"React InstantSearch","description":"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.","status":"active","version":"7.29.0","language":"javascript","source_language":"en","source_url":"https://github.com/algolia/instantsearch","tags":["javascript","algolia","components","fast","instantsearch","react","search","typescript"],"install":[{"cmd":"npm install react-instantsearch","lang":"bash","label":"npm"},{"cmd":"yarn add react-instantsearch","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-instantsearch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to communicate with Algolia's search API.","package":"algoliasearch","optional":false},{"reason":"Peer dependency for React components.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"This is the primary wrapper component for your search interface. CommonJS `require()` is not recommended for modern React projects and may cause issues.","wrong":"const InstantSearch = require('react-instantsearch');","symbol":"InstantSearch","correct":"import { InstantSearch } from 'react-instantsearch';"},{"note":"One of many pre-built UI widgets. All UI widgets are named exports from the main package.","wrong":"import SearchBox from 'react-instantsearch/lib/SearchBox';","symbol":"SearchBox","correct":"import { SearchBox } from 'react-instantsearch';"},{"note":"The Hits component displays search results. While connectors exist for advanced use cases, the component itself is a named export.","wrong":"import { connectHits } from 'react-instantsearch/lib/connectors';","symbol":"Hits","correct":"import { Hits } from 'react-instantsearch';"},{"note":"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.","wrong":"import algoliasearch from 'algoliasearch';","symbol":"algoliasearch client","correct":"import { liteClient as algoliasearch } from 'algoliasearch/lite';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { liteClient as algoliasearch } from 'algoliasearch/lite';\nimport { InstantSearch, SearchBox, Hits } from 'react-instantsearch';\nimport 'instantsearch.css/themes/algolia.css'; // Optional: for basic styling\n\n// Replace with your Algolia App ID and Search API Key\nconst searchClient = algoliasearch(\n  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID ?? 'latency',\n  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY ?? '6be0576ff61c053d5f9a3225e2a90f76'\n);\n\nconst App = () => (\n  <InstantSearch indexName=\"bestbuy\" searchClient={searchClient}>\n    <h1>React InstantSearch Example</h1>\n    <SearchBox placeholder=\"Search products...\" />\n    <Hits />\n  </InstantSearch>\n);\n\nconst root = ReactDOM.createRoot(document.getElementById('root')!);\nroot.render(<App />);","lang":"typescript","description":"This quickstart demonstrates setting up a basic instant search interface with a search box and result list, connecting to an Algolia index."},"warnings":[{"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()`.","message":"React InstantSearch versions 6 and above are designed for ESM environments. Using CommonJS `require()` or older build setups may lead to issues.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"React InstantSearch relies on React Hooks, introduced in React 16.8. Older versions of React will not be compatible.","severity":"breaking","affected_versions":"<16.8.0"},{"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.","message":"React InstantSearch components provide functionality but minimal styling by default. You need to import a theme or provide your own CSS.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use the `liteClient` named import from `algoliasearch/lite` for browser-based applications: `import { liteClient as algoliasearch } from 'algoliasearch/lite';`.","message":"Using the full `algoliasearch` client bundle (`import algoliasearch from 'algoliasearch';`) in a browser environment can unnecessarily increase your bundle size.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `searchClient` prop passed to `<InstantSearch>` is either undefined, null, or not a valid Algolia search client instance.","error":"TypeError: Cannot read properties of undefined (reading 'init') OR searchClient is not a function"},{"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}>`).","cause":"The `indexName` prop is missing or empty on the `<InstantSearch>` component.","error":"Error: No index found. Please make sure to pass an 'indexName' prop to the <InstantSearch> component."},{"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.","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.","error":"Error: Hooks can only be called inside of the body of a function component."}],"ecosystem":"npm"}