Upgrading React InstantSearch Hooks

Components

React InstantSearch Hooks provides most of the same UI components as React InstantSearch. When no UI component is available, you can use the matching Hooks to build it yourself.

React InstantSearch	React InstantSearch Hooks
`<Breadcrumb>`	`<Breadcrumb>`
`<ClearRefinements>`	`<ClearRefinements>`
`<Configure>`	`<Configure>`
`<CurrentRefinements>`	`<CurrentRefinements>`
`<DynamicWidgets>`	`<DynamicWidgets>`
`<EXPERIMENTAL_Answers>`	`useConnector(connectAnswers)` (no UI component)
`EXPERIMENTAL_useAnswers()`	`useConnector(connectAnswers)` (no UI component)
`<ExperimentalConfigureRelatedItems>`	`useConnector(connectConfigureRelatedItems)` (no UI component)
`<HierarchicalMenu>`	`<HierarchicalMenu>`
`<Highlight>`	`<Highlight>`
`<Hits>`	`<Hits>`
`<HitsPerPage>`	`<HitsPerPage>`
`<Index>`	`<Index>`
`<InfiniteHits>`	`<InfiniteHits>`
`<InstantSearch>`	`<InstantSearch>`
`<Menu>`	`<Menu>`
`<MenuSelect>`	`useMenu()` (no UI component)
`<NumericMenu>`	`useConnector(connectNumericMenu)` (no UI component)
`<Pagination>`	`<Pagination>`
`<Panel>`	No equivalent available
`<PoweredBy>`	`<PoweredBy>`
`<QueryRuleContext>`	`useQueryRules()` (no UI component)
`<QueryRuleCustomData>`	`useQueryRules()` (no UI component)
`<RangeInput>`	`<RangeInput>`
`<RangeSlider>`	`useRange()` (no UI component)
`<RatingMenu>`	`useMenu()` (no UI component)
`<RefinementList>`	`<RefinementList>`
`<RelevantSort>`	`useConnector(connectRelevantSort)` (no UI component)
`<ScrollTo>`	No equivalent available
`<SearchBox>`	`<SearchBox>`
`<Snippet>`	`<Snippet>`
`<SortBy>`	`<SortBy>`
`<Stats>`	No equivalent available
`<ToggleRefinement>`	`<ToggleRefinement>`
`<VoiceSearch>`	`useConnector(connectVoiceSearch)` (no UI component)

Component props differ slightly between React InstantSearch and React InstantSearch Hooks. Refer to the API reference of each component for information.

API Reference React InstantSearch Hooks API Reference

React InstantSearch API Reference

Using connectors and Hooks

React InstantSearch Hooks is a bridge between InstantSearch.js connectors and React Hooks. The connectors from React InstantSearch and InstantSearch.js were historically different APIs, meaning there are differences between the props that React InstantSearch connectors accept and the new Hooks.

Refer to the API reference to see the new props.

The React InstantSearch Hooks package uses TypeScript natively. If your editor supports code completion (IntelliSense), you can use it to discover the new props.

API reference React InstantSearch Hooks

Creating connectors

The connector API has changed to use InstantSearch.js connectors. The previous createConnector() function is no longer available.

React InstantSearch Hooks works with all InstantSearch.js connectors—official Algolia connectors, and community ones.

To create your own Hook, you can use an existing connector or create your InstantSearch.js connector.

Since React Hooks are headless, you can skip the Rendering and Widget parts of the guide.

Guides Creating Your Own Hooks

Routing

Routing now follows the InstantSearch.js routing APIs with the <InstantSearch> routing prop.

API reference <InstantSearch> routing prop

Guides Sync Your URLs with InstantSearch.js

Server-side rendering (SSR)

The server APIs have been simplified in React InstantSearch Hooks.

Replace findResultsState() with getServerState(). This new API accepts an element <App />. You can pass props directly to <App />.

In your server code, you don’t need to provide your index name and your search client anymore, because they’re already in your <App>.

Copy
 import express from 'express';
 import React from 'react';
 import { renderToString } from 'react-dom/server';
-import { findResultsState } from 'react-instantsearch-dom/server';
+import { getServerState } from 'react-instantsearch-hooks-server';
 import App from './App';

-const indexName = 'instant_search';
-const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 const app = express();

 app.get('/', async (req, res) => {
-  const searchState = { /* ... */ };
-  const serverState = {
-    resultsState: await findResultsState(App, {
-      searchClient,
-      indexName,
-      searchState,
-    }),
-    searchState,
-  };
+  const serverState = await getServerState(<App />);
   const html = renderToString(<App serverState={serverState} />);

   res.send(
     `
   <!DOCTYPE html>
   <html>
     <head>
       <script>window.__SERVER_STATE__ = ${JSON.stringify(serverState)};</script>
     </head>
     <body>
       <div id="root">${html}</div>
     </body>
     <script src="/assets/bundle.js"></script>
   </html>
     `
   );
 });

 app.listen(8080);

You don’t need to pass any props to <InstantSearch> to support SSR, only wrap the component to render on the server with <InstantSearchSSRProvider>. Then, pass the server state by spreading the getServerState() prop.

Copy
 import algoliasearch from 'algoliasearch/lite';
 import React from 'react';
-import { InstantSearch } from 'react-instantsearch-dom';
+import {
+  InstantSearch,
+  InstantSearchSSRProvider,
+} from 'react-instantsearch-hooks-web';

 const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 function App(props) {
   return (
+    <InstantSearchSSRProvider {...props.serverState}>
       <InstantSearch
         indexName="instant_search"
         searchClient={searchClient}
-        resultsState={props.serverState.resultsState}
-        onSearchParameters={props.onSearchParameters}
-        widgetsCollector={props.widgetsCollector}
       >
         {/* Widgets */}
       </InstantSearch>
+    </InstantSearchSSRProvider>
   );
 }

 export default App;

API reference getServerState()

Guides Server-Side Rendering with React InstantSearch Hooks

Types

Types are now available in React InstantSearch Hooks.

You can uninstall all InstantSearch types coming from DefinitelyTyped.

Copy

1
2
3
yarn remove @types/react-instantsearch-dom @types/react-instantsearch-core @types/react-instantsearch
# or
npm uninstall @types/react-instantsearch-dom @types/react-instantsearch-core @types/react-instantsearch

In React InstantSearch, every widget has a defaultRefinement prop. This doesn’t exist in React InstantSearch hooks and is replaced with initialUiState.

Controlled mode

The props searchState and onSearchStateChange are equivalent to the onStateChange prop.

Installation

Autocomplete

Did you find this page helpful?