React InstantSearch Core

Common errors

• Cannot resolve module 'algoliasearch'

  cause The `algoliasearch` package is a peer dependency but is not installed in the project.
  fix Install `algoliasearch`: `npm install algoliasearch` or `yarn add algoliasearch`.

• Error: Invalid `searchClient`. It looks like `algoliasearch` was not passed to the `InstantSearch` component.

  cause The `searchClient` prop of the `InstantSearch` component is either missing or an invalid Algolia search client instance.
  fix Ensure you are passing a valid `algoliasearch` client instance, like `algoliasearch('APP_ID', 'API_KEY')`, to the `searchClient` prop of the `InstantSearch` component.

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

  cause React Hooks like `useInstantSearch` are being called outside of a functional React component or a custom Hook.
  fix Ensure all calls to `useInstantSearch` (or other React Hooks) are made within the top level of a functional component or a custom Hook.

Warnings

• gotcha 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.
  Fix: If expecting visual components, install `react-instantsearch` instead. If building custom UI, ensure you implement rendering logic for your components.
• breaking React InstantSearch v7 requires React version 16.8.0 or newer due to its reliance on React Hooks. Older React versions are not supported.
  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`.
• breaking The `algoliasearch` peer dependency has specific version requirements (>= 3.1 < 6). Using an incompatible version may lead to runtime errors or unexpected behavior.
  Fix: Ensure your installed `algoliasearch` client version is compatible with the `react-instantsearch-core` peer dependency range. Upgrade or downgrade `algoliasearch` as needed.
• gotcha The `InstantSearch` component requires a valid `searchClient` prop (an instance of `algoliasearch`) and an `indexName`. Incorrect or missing values will prevent search functionality.
  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.

Install

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

Imports

• InstantSearch
  wrong:

  import InstantSearch from 'react-instantsearch-core'

  correct:

  import { InstantSearch } from 'react-instantsearch-core'

  This is the main context provider component for InstantSearch. It is a named export.
• useInstantSearch

  import { useInstantSearch } from 'react-instantsearch-core'

  A React Hook to access the InstantSearch context and search state. Primarily used for creating custom widgets or accessing search data directly.
• connectSearchBox

  import { connectSearchBox } from 'react-instantsearch-core'

  A higher-order component (HOC) connector for creating custom search box widgets. Often used when hooks are not suitable or for older patterns.
• Hits
  wrong:

  import { Hits } from 'react-instantsearch-core'

  correct:

  import { Hits } from 'react-instantsearch'

  Pre-built UI components like `Hits`, `RefinementList`, etc., are provided by `react-instantsearch`, not `react-instantsearch-core` (which is headless).

Quickstart

Demonstrates setting up InstantSearch with a custom search box and hits display using `useInstantSearch` hooks.

import React, { useState, useEffect } from 'react';
import algoliasearch from 'algoliasearch';
import { InstantSearch, useInstantSearch } from 'react-instantsearch-core';

const searchClient = algoliasearch(
  process.env.ALGOLIA_APP_ID ?? 'YOUR_APP_ID',
  process.env.ALGOLIA_SEARCH_API_KEY ?? 'YOUR_SEARCH_API_KEY'
);
const indexName = 'your_index_name';

function CustomSearchBox() {
  const { uiState, setUiState } = useInstantSearch();
  const [query, setQuery] = useState(uiState.query || '');

  useEffect(() => {
    // Synchronize local query state with InstantSearch's UI state
    if (uiState.query !== query) {
      setQuery(uiState.query || '');
    }
  }, [uiState.query]);

  const handleChange = (event) => {
    const newQuery = event.target.value;
    setQuery(newQuery);
    setUiState(prevUiState => ({ ...prevUiState, query: newQuery }));
  };

  return (
    <input
      type="search"
      placeholder="Search..."
      value={query}
      onChange={handleChange}
      style={{ padding: '10px', width: '300px', marginBottom: '20px' }}
    />
  );
}

function CustomHits() {
  const { results } = useInstantSearch();

  return (
    <div>
      {results.hits.length > 0 ? (
        <ul>
          {results.hits.map(hit => (
            <li key={hit.objectID} style={{ marginBottom: '10px' }}>
              {/* Assuming your hits have a 'name' property */}
              <h3>{hit.name}</h3>
              <p>{hit.description}</p>
            </li>
          ))}
        </ul>
      ) : (
        <p>No results found.</p>
      )}
    </div>
  );
}

function App() {
  return (
    <InstantSearch 
      searchClient={searchClient} 
      indexName={indexName}
      initialUiState={{ [indexName]: { query: '' } }}
    >
      <h1>My Custom Search</h1>
      <CustomSearchBox />
      <CustomHits />
    </InstantSearch>
  );
}

export default App;