Upgrade Guides for InstantSearch

Upgrade from v5 to v6

Version 6 of React InstantSearch leverages the Context API that was released part of React 16.3.0. This means version 6 of React InstantSearch requires React 16.3.0 or higher.

React InstantSearch is compliant with StrictMode, for which we introduced the following breaking changes:

SSR

The SSR API only uses the server module on the server instead of on both the server and the client.

We added support for searchClient hydration. The request used to happen on the server, but also on the client once the app was mounted. Because the state is passed from the server to the client, the initial client request was useless and is now re-used from the server request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// server.js

import React from 'react';
import { renderToString } from 'react-dom/server';
+import { findResultsState } from 'react-instantsearch-dom/server';
-import { App, findResultsState } from './App';
+import { App } from './App';

+const indexName = 'instant_search';
+const searchClient = algoliasearch(
+  'latency',
+  '6be0576ff61c053d5f9a3225e2a90f76'
+);

server.get('/', async (req, res) => {
  const initialState = {
-    resultsState: await findResultsState(App)
+    resultsState: await findResultsState(App, {
+      indexName,
+      searchClient
+    })
  };

  const plainHTML = renderToString(<App {...initialState} />);

  // ...
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// browser.js

import React from 'react';
import { hydrate } from 'react-dom';
import { App } from './App';

+const indexName = 'instant_search';
+const searchClient = algoliasearch(
+  'latency',
+  '6be0576ff61c053d5f9a3225e2a90f76'
+);

hydrate(
  <App
    {...window.__APP_INITIAL_STATE__}
+   indexName={indexName}
+   searchClient={searchClient}
  />,
  document.getElementById('root')
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// App.js

import React from 'react';
-import algoliasearch from 'algoliasearch/lite';
-import { createInstantSearch } from 'react-instantsearch-dom/server';
-import { SearchBox } from 'react-instantsearch-dom';
+import { InstantSearch, SearchBox } from 'react-instantsearch-dom';

-const { InstantSearch, findResultsState } = createInstantSearch();

-const searchClient = algoliasearch(
-  'latency',
-  '6be0576ff61c053d5f9a3225e2a90f76'
-);

-const App = ({ resultsState }) => (
+const App = ({ indexName, searchClient, resultsState, onSearchParameters }) => (
  <InstantSearch
-   indexName="instant_search"
+   indexName={indexName}
    searchClient={searchClient}
    resultsState={resultsState}
+   onSearchParameters={onSearchParameters}
  >
    <SearchBox />
  </InstantSearch>
);

-export { App, findResultsState };
+export { App };

You might notice some duplications inside the server and browser modules above. We duplicated the declaration of indexName and searchClient. We can avoid this with a createApp function that returns the App and the props that we have to provide. You can find this pattern applied inside our complete SSR example.

Removed support for appId and apiKey

We removed support for the appId and apiKey props on InstantSearch. Configure an algoliasearch client and pass it to the searchClient prop to configure your credentials.

The benefit of this change is that we no longer ship algoliasearch with React InstantSearch and you can use any SearchClient you want to use.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import React from 'react';
+import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SearchBox } from 'react-instantsearch-dom';

+const searchClient = algoliasearch(
+  'latency',
+  '6be0576ff61c053d5f9a3225e2a90f76'
+);

const App = () => (
  <InstantSearch
-   appId="latency"
-   apiKey="6be0576ff61c053d5f9a3225e2a90f76"
    indexName="instant_search"
+   searchClient={searchClient}
  >
    <SearchBox />
  </InstantSearch>
);

Removed support for root in InstantSearch and Index

The root prop in InstantSearch and Index is no longer used. The top-level element is the Context.Provider, which does not render anything.

You can wrap the element provided to root directly around InstantSearch, which is useful for React Native users.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// ...

const App = () => (
+  <section style={{ display: 'flex' }}>
    <InstantSearch
      indexName="instant_search"
      searchClient={searchClient}
-      root={{
-        Root: 'section',
-        props: {
-          style: {
-            display: 'flex',
-          },
-        },
-      }}
    >
      <SearchBox />
    </InstantSearch>
+  <section>
);

algoliasearch-helper 3.x.x

We upgraded algoliasearch-helper to version 3. This means that if you interact with a SearchResults or SearchParameters object, the breaking changes there will affect your code. This usually only impacts you if you create a custom connector with createConnector.

There are no longer default values for the page (0) and query (‘’) search parameters. Both default to undefined when no value is assigned.

The function getQueryParameter was removed in favor of calling the getter for that parameter.

This version of algoliasearch-helper no longer includes Lodash, which significantly reduces its bundle size (from 27.5KB to 9.1KB Gzipped). If you’re using any methods from the helper, searchParameters or searchResults, please refer to the package’s detailed changelog.

Package imports since 5.2.0

With the release of the version 5.2.0, we completely revamped the architecture of the package while keeping it backward compatible. The only case where changes are required is when you are using the private imports:

1
2
3
4
5
// Still works with `react-instantsearch` ≥ `5.2.0`
import { InstantSearch } from 'react-instantsearch/dom';

// Doesn't work with `react-instantsearch` ≥ `5.2.0`
import { InstantSearch } from 'react-instantsearch/es/widgets/SearchBox';

We’ve never documented the latter although it was handy to use; the default import was not compatible with tree shaking. For this reason, we decided to update our package to be compatible with tree shaking by default. To achieve this, we decided to publish three new packages:

• react-instantsearch-core: contains all the core logic of React InstantSearch
• react-instantsearch-dom: contains the DOM specific widgets and components
• react-instantsearch-native: contains the React Native specific widgets and components

The react-instantsearch-core package is used internally by the two others. You don’t need to use this package on its own most of the time. You might want to use it for a new “binding”. We only support React DOM and React Native but the core package is not tied to any rendering engine. It means that you can create your own binding for React 360 for example.

This split also allows using the correct peerDependencies for each package. It was not the case previously because the package was the target of both React DOM and React Native. You can now have a clear vision about which version of React the package depends on:

• react-instantsearch-core: has a peer dependency on react ≥ 15.3.0 < 17
• react-instantsearch-dom: has a peer dependency on react ≥ 15.3.0 < 17 and react-dom ≥ 15.3.0 < 17
• react-instantsearch-native: has a peer dependency on react ≥ 15.3.0 < 17 and react-native ≥ 0.32.0

As this new architecture is backward compatible, we encourage all our users to update to the new package. We recommend doing so because the library is correctly tree shaken with Webpack ≥ 4. Here are some metrics about the two different versions:

The sizes are after gzip. The sample application uses: Configure, SearchBox, ClearRefinements, RefinementList, Hits, Custom Hits (with the connector, Pagination.

The package react-instantsearch is deprecated in favor of react-instantsearch-dom and react-instantsearch-native.

Migration for React DOM

The first step is to remove the package react-instantsearch:

1
yarn remove react-instantsearch

The second step is to install the package react-instantsearch-dom:

1
yarn add react-instantsearch-dom

The last step is to update all your imports to the new package:

1
2
3
4
5
6
7
8
9
// With `react-instantsearch`
import { createConnector } from 'react-instantsearch';
import { InstantSearch } from 'react-instantsearch/dom';
import { connectMenu } from 'react-instantsearch/connectors';
import { createInstantSearch } from 'react-instantsearch/server';

// With `react-instantsearch-dom`
import { createConnector, InstantSearch, connectMenu } from 'react-instantsearch-dom';
import { createInstantSearch } from 'react-instantsearch-dom/server';

Migration for React Native

The first step is to remove the package react-instantsearch:

1
yarn remove react-instantsearch

The second step is to install the package react-instantsearch-native:

1
yarn add react-instantsearch-native

The last step is to update all your imports to the new package:

1
2
3
4
5
6
7
// with `react-instantsearch`
import { createConnector } from 'react-instantsearch';
import { InstantSearch } from 'react-instantsearch/native';
import { connectMenu } from 'react-instantsearch/connectors';

// with `react-instantsearch-native`
import { createConnector, InstantSearch, connectMenu } from 'react-instantsearch-native';

Upgrade from v4 to v5

React V5 introduces a complete revamp of the HTML output of most widgets. The goal of this release is to provide improved semantics to our users.

This release also introduces a new CSS naming convention which will be reused across all InstantSearch libraries. This will enable the possibility to develop cross-libraries CSS themes easily.

This guide will provide step-by-step migration information for each widget & connector.

Migration steps

Updating widget & connector names

A few widgets & connectors have been renamed in order to improve the meaning as well as consistency between each InstantSearch library. You will need to update your imports to match new names.

Complete list of changes:

Updating prop names

Some of the props have been renamed for a better consistency across the library. See below the list of all of them:

• attributeName → attribute (multiple widgets)
• limitMin → limit (HierarchicalMenu, Menu, RefinementList)
• limitMax → showMoreLimit (HierarchicalMenu, Menu, RefinementList)
• maxPages → totalPages (Pagination)
• pagesPadding → padding (Pagination)
• title → header (Panel)
• submitComponent → submit (SearchBox)
• resetComponent → reset (SearchBox)
• loadingIndicatorComponent → loadingIndicator (SearchBox)
• withSearchBox → searchable (Menu, RefinementList)

Please refer to Widgets changes & Connectors changes sections for more detail informations.

Removing deprecation

We introduced a couple of months ago a warning about the usage of searchForFacetValues in favour of searchForItems & withSearchBox (now renamed searchable). This warning has been removed and so is the legacy API. Update your code if it’s not already the case. See below for the list of changes:

• searchForFacetValues → withSearchBox → searchable (RefinementList, Menu)
• searchForFacetValues → searchForItems (createConnector, connectRefinementList, connectMenu)
• searchParameters → removed on <InstantSearch> in favor of <Configure />

Please refer to Widgets changes & Connectors changes sections for more detail informations.

Updating styles

We are now making a unified theme for all InstantSearch versions, and React InstantSearch is the first to use it. It’s published as instantsearch.css, and causes the deprecation and removal of react-instantsearch-theme-algolia.

Here is the new jsDelivr links for the theme:

1
2
3
4
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.3.1/themes/reset-min.css" integrity="sha256-t2ATOGCtAIZNnzER679jwcFcKYfLlw01gli6F6oszk8=" crossorigin="anonymous">

<!-- or -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.4.5/themes/satellite-min.css" integrity="sha256-TehzF/2QvNKhGQrrNpoOb2Ck4iGZ1J/DI4pkd2oUsBc=" crossorigin="anonymous">

The reset theme is shipped with the satellite one, so no need to import it when you are using the satellite theme.

You can also use npm to install it, please refer to the Styling Widgets guide for more informations.

The CSS naming convention used for widgets has been changed in favour of the SUIT CSS methodology.

In order to fix broken stylings, please refer to the CSS naming equivalency table of each widget in the Widgets changes section.

Two new CSS themes have also been written:

• reset.css
• satellite.css

We strongly recommend to use at least reset.css in order to avoid the visual side effects induced by the new semantic changes made on most widgets.

Please refer to the Styling Widgets guide for more information on how to install and use those CSS themes.

Adding className

All the built-in widgets now accept a prop className that will be forwarded to the root element of the widgets.

1
2
3
4
5
6
7
8
9
<RefinementList
  className="MyCustomRefinementList"
  attribute="category"
/>

// Will produce a DOM with
<div className="ais-RefinementList MyCustomRefinementList">
  // content of the RefinementList
</div>

Widgets changes

Note: the equivalency table only shows the replacement classes for existing classes. New CSS classes are also available. For more details, please refer to the Widgets API Reference.

InstantSearch

See the widget documentation page.

Naming

• No change.

Behavior

• searchParameters → removed in favour of <Configure />

CSS classes equivalency table

• No change.

Breadcrumb

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

ClearAll

See the widget documentation page.

Naming

• Renamed to ClearRefinements.

Behavior

• No change.

CSS classes equivalency table

CurrentRefinements

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

HierarchicalMenu

See the widget documentation page.

Naming

• limitMin → limit
• limitMax → showMoreLimit

Behavior

• No change.

CSS classes equivalency table

Highlight

See the widget documentation page.

Naming

• attributeName → attribute

Behavior

• No change.

CSS classes equivalency table

Hits

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

HitsPerPage

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

InfiniteHits

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

Menu

See the widget documentation page.

Naming

• attributeName → attribute
• limitMin → limit
• limitMax → showMoreLimit
• withSearchBox → searchable

Behavior

• No change.

CSS classes equivalency table

MenuSelect

See the widget documentation page.

Naming

• attributeName → attribute

Behavior

• No change.

CSS classes equivalency table

MultiRange

See the widget documentation page.

Naming

• Renamed to NumericMenu.

• attributeName → attribute

Behavior

• No change.

CSS classes equivalency table

Pagination

See the widget documentation page.

Naming

• maxPages → totalPages
• pagesPadding → padding

Behavior

• No change.

CSS classes equivalency table

Panel

See the widget documentation page.

Naming

• title → header

Behavior

• No change.

CSS classes equivalency table

PoweredBy

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

RangeInput

See the widget documentation page.

Naming

• attributeName → attribute

Behavior

• The default precision previously 2 has been updated to 0.

CSS classes equivalency table

RefinementList

See the widget documentation page.

Naming

• attributeName → attribute
• limitMin → limit
• limitMax → showMoreLimit
• withSearchBox → searchable

Behavior

• No change.

CSS classes equivalency table

SearchBox

See the widget documentation page.

Naming

• submitComponent → submit
• resetComponent → reset
• loadingIndicatorComponent → loadingIndicator

Behavior

• No change.

CSS classes equivalency table

SortBy

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

StarRating

See the widget documentation page.

Naming

• Renamed to RatingMenu.

• attributeName → attribute

Behavior

• No change.

CSS classes equivalency table

Stats

See the widget documentation page.

Naming

• No change.

Behavior

• No change.

CSS classes equivalency table

Toggle

See the widget documentation page.

Naming

• Renamed to ToggleRefinement.

• attributeName → attribute

Behavior

• No change.

CSS classes equivalency table

Connectors changes

createConnector

See the connector documentation page.

Naming

• searchForFacetValues → searchForItems

Behavior

• No change.

connectCurrentRefinements

See the connector documentation page.

Naming

• The property attributeName in the provided props items has been renamed attribute.

Behavior

• No change.

connectHierarchicalMenu

See the connector documentation page.

Naming

• limitMin → limit
• limitMax → showMoreLimit

Behavior

• No change.

connectHighlight

See the connector documentation page.

Naming

• The property attributeName in the provided props highlight has been renamed attribute.

Behavior

• No change.

connectMenu

See the connector documentation page.

Naming

• attributeName → attribute
• limitMin → limit
• limitMax → showMoreLimit
• withSearchBox → searchable
• searchForFacetValues → searchForItems

Behavior

• No change.

connectMultiRange

See the connector documentation page.

Naming

• Renamed to connectNumericMenu.

• attributeName → attribute

Behavior

• No change.

connectPagination

See the connector documentation page.

Naming

• maxPages → totalPages
• pagesPadding → padding

Behavior

• No change.

connectRange

See the connector documentation page.

Naming

• attributeName → attribute

Behavior

• The default precision previously 2 has been updated to 0.

connectRefinementList

See the connector documentation page.

Naming

• attributeName → attribute
• limitMin → limit
• limitMax → showMoreLimit
• withSearchBox → searchable
• searchForFacetValues → searchForItems

Behavior

• No change.

connectToggle

See the connector documentation page.

Naming

• Renamed to connectToggleRefinement.

• attributeName → attribute

Behavior

• No change.

Upgrade from v3 to v4

Check out our v4 announcement post