{"id":11731,"library":"react-instantsearch-core","title":"React InstantSearch Core","description":"React InstantSearch Core is a headless UI library for React applications, enabling developers to build highly customized, lightning-fast search interfaces powered by Algolia. It provides a set of renderless components and hooks that manage the search logic and state, abstracting away the complexities of interacting directly with the Algolia API. Unlike `react-instantsearch`, which offers pre-built DOM components, `react-instantsearch-core` focuses on providing low-level primitives suitable for both web and React Native projects, allowing maximum flexibility in UI implementation. The library is currently stable at version 7.29.0 and is actively maintained within the Algolia InstantSearch ecosystem, receiving frequent updates, typically monthly, to align with new features and improvements across the InstantSearch family of libraries. Its core differentiator lies in its headless nature, empowering developers to create unique search experiences without being constrained by opinionated UI components.","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-core","lang":"bash","label":"npm"},{"cmd":"yarn add react-instantsearch-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-instantsearch-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for communicating with Algolia APIs and managing search state.","package":"algoliasearch","optional":false},{"reason":"Core dependency for building React components.","package":"react","optional":false}],"imports":[{"note":"This is the main context provider component for InstantSearch. It is a named export.","wrong":"import InstantSearch from 'react-instantsearch-core'","symbol":"InstantSearch","correct":"import { InstantSearch } from 'react-instantsearch-core'"},{"note":"A React Hook to access the InstantSearch context and search state. Primarily used for creating custom widgets or accessing search data directly.","symbol":"useInstantSearch","correct":"import { useInstantSearch } from 'react-instantsearch-core'"},{"note":"A higher-order component (HOC) connector for creating custom search box widgets. Often used when hooks are not suitable or for older patterns.","symbol":"connectSearchBox","correct":"import { connectSearchBox } from 'react-instantsearch-core'"},{"note":"Pre-built UI components like `Hits`, `RefinementList`, etc., are provided by `react-instantsearch`, not `react-instantsearch-core` (which is headless).","wrong":"import { Hits } from 'react-instantsearch-core'","symbol":"Hits","correct":"import { Hits } from 'react-instantsearch'"}],"quickstart":{"code":"import React, { useState, useEffect } from 'react';\nimport algoliasearch from 'algoliasearch';\nimport { InstantSearch, useInstantSearch } from 'react-instantsearch-core';\n\nconst searchClient = algoliasearch(\n process.env.ALGOLIA_APP_ID ?? 'YOUR_APP_ID',\n process.env.ALGOLIA_SEARCH_API_KEY ?? 'YOUR_SEARCH_API_KEY'\n);\nconst indexName = 'your_index_name';\n\nfunction CustomSearchBox() {\n const { uiState, setUiState } = useInstantSearch();\n const [query, setQuery] = useState(uiState.query || '');\n\n useEffect(() => {\n // Synchronize local query state with InstantSearch's UI state\n if (uiState.query !== query) {\n setQuery(uiState.query || '');\n }\n }, [uiState.query]);\n\n const handleChange = (event) => {\n const newQuery = event.target.value;\n setQuery(newQuery);\n setUiState(prevUiState => ({ ...prevUiState, query: newQuery }));\n };\n\n return (\n \n );\n}\n\nfunction CustomHits() {\n const { results } = useInstantSearch();\n\n return (\n
\n {results.hits.length > 0 ? (\n \n ) : (\n

No results found.

\n )}\n
\n );\n}\n\nfunction App() {\n return (\n \n

My Custom Search

\n \n \n \n );\n}\n\nexport default App;\n","lang":"typescript","description":"Demonstrates setting up InstantSearch with a custom search box and hits display using `useInstantSearch` hooks."},"warnings":[{"fix":"If expecting visual components, install `react-instantsearch` instead. If building custom UI, ensure you implement rendering logic for your components.","message":"This package (`react-instantsearch-core`) provides renderless components and hooks for search logic. It does *not* include any visual UI components. Developers must build their own UI using the provided hooks and connectors. If you need pre-built DOM-rendering components, use `react-instantsearch` instead.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your project's `react` and `react-dom` dependencies to version `^16.8.0` or newer. The current peer dependency range is `>= 16.8.0 < 20`.","message":"React InstantSearch v7 requires React version 16.8.0 or newer due to its reliance on React Hooks. Older React versions are not supported.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your installed `algoliasearch` client version is compatible with the `react-instantsearch-core` peer dependency range. Upgrade or downgrade `algoliasearch` as needed.","message":"The `algoliasearch` peer dependency has specific version requirements (>= 3.1 < 6). Using an incompatible version may lead to runtime errors or unexpected behavior.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Always provide a properly initialized `searchClient` from `algoliasearch` and the `indexName` of your Algolia index to the `InstantSearch` component. Ensure your API keys are correct and have appropriate permissions.","message":"The `InstantSearch` component requires a valid `searchClient` prop (an instance of `algoliasearch`) and an `indexName`. Incorrect or missing values will prevent search functionality.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `algoliasearch`: `npm install algoliasearch` or `yarn add algoliasearch`.","cause":"The `algoliasearch` package is a peer dependency but is not installed in the project.","error":"Cannot resolve module 'algoliasearch'"},{"fix":"Ensure you are passing a valid `algoliasearch` client instance, like `algoliasearch('APP_ID', 'API_KEY')`, to the `searchClient` prop of the `InstantSearch` component.","cause":"The `searchClient` prop of the `InstantSearch` component is either missing or an invalid Algolia search client instance.","error":"Error: Invalid `searchClient`. It looks like `algoliasearch` was not passed to the `InstantSearch` component."},{"fix":"Ensure all calls to `useInstantSearch` (or other React Hooks) are made within the top level of a functional component or a custom Hook.","cause":"React Hooks like `useInstantSearch` are being called outside of a functional React component or a custom Hook.","error":"Error: Hooks can only be called inside of the body of a function component."}],"ecosystem":"npm"}