Upgrade Guides for InstantSearch

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.3.1/themes/algolia-min.css" integrity="sha256-HB49n/BZjuqiCtQQf49OdZn63XuKFaxcIHWf0HNKte8=" crossorigin="anonymous">

The reset theme is shipped with the algolia one, so no need to import it when you are using the algolia 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
• algolia.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