Concepts / Building Search UI / Upgrade guides
Jan. 07, 2019

Upgrade guides

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:

  Create React App + Webpack 3 Webpack 4
react-instantsearch/dom (CJS) 108 kB 104 kB
react-instantsearch-dom (ESM) 105 kB (-2.7%) 87 kB (-16.3%)

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:

Old name New name
ClearAll ClearRefinements
MultiRange NumericMenu
StarRating RatingMenu
Toggle ToggleRefinement
connectMultiRange connectNumericMenu
connectToggle connectToggleRefinement

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:

  • attributeNameattribute (multiple widgets)
  • limitMinlimit (HierarchicalMenu, Menu, RefinementList)
  • limitMaxshowMoreLimit (HierarchicalMenu, Menu, RefinementList)
  • maxPagestotalPages (Pagination)
  • pagesPaddingpadding (Pagination)
  • titleheader (Panel)
  • submitComponentsubmit (SearchBox)
  • resetComponentreset (SearchBox)
  • loadingIndicatorComponentloadingIndicator (SearchBox)
  • withSearchBoxsearchable (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:

  • searchForFacetValueswithSearchBoxsearchable (RefinementList, Menu)
  • searchForFacetValuessearchForItems (createConnector, connectRefinementList, connectMenu)
  • searchParametersremoved 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
5
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.0.0/themes/reset-min.css">

<!-- or -->

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.0.0/themes/algolia-min.css">

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

  • searchParametersremoved in favour of <Configure />

CSS classes equivalency table

  • No change.

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Breadcrumb__root .ais-Breadcrumb
.ais-Breadcrumb__itemLinkRoot Removed. Target with :first-child instead.
.ais-Breadcrumb__rootLabel Removed. Target with :first-child instead.
.ais-Breadcrumb__item .ais-Breadcrumb-item
.ais-Breadcrumb__itemLink .ais-Breadcrumb-link
.ais-Breadcrumb__itemLabel Removed. Use .ais-Breadcrumb-link instead.
.ais-Breadcrumb__itemDisabled .ais-Breadcrumb-item--selected
.ais-Breadcrumb__separator .ais-Breadcrumb-separator
.ais-Breadcrumb__noRefinement .ais-Breadcrumb--noRefinement

ClearAll

See the widget documentation page.

Naming

  • Renamed to ClearRefinements.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-ClearAll__root .ais-ClearRefinements-button

CurrentRefinements

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-CurrentRefinements__root .ais-CurrentRefinements
.ais-CurrentRefinements__items .ais-CurrentRefinements-list
.ais-CurrentRefinements__item .ais-CurrentRefinements-item
.ais-CurrentRefinements__itemLabel .ais-CurrentRefinements-label
.ais-CurrentRefinements__itemClear .ais-CurrentRefinements-delete
.ais-CurrentRefinements__noRefinement .ais-CurrentRefinements--noRefinement

HierarchicalMenu

See the widget documentation page.

Naming

  • limitMinlimit
  • limitMaxshowMoreLimit

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-HierarchicalMenu__root .ais-HierarchicalMenu
.ais-HierarchicalMenu__items .ais-HierarchicalMenu-list
.ais-HierarchicalMenu__item .ais-HierarchicalMenu-item
.ais-HierarchicalMenu__itemSelected .ais-HierarchicalMenu-item--selected
.ais-HierarchicalMenu__itemParent .ais-HierarchicalMenu-item--parent
.ais-HierarchicalMenu__itemSelectedParent Removed. Use .ais-HierarchicalMenu-item--selected.ais-HierarchicalMenu-item--parent instead.
.ais-HierarchicalMenu__itemLink .ais-HierarchicalMenu-link
.ais-HierarchicalMenu__itemLabel .ais-HierarchicalMenu-label
.ais-HierarchicalMenu__itemCount .ais-HierarchicalMenu-count
.ais-HierarchicalMenu__itemItems .ais-HierarchicalMenu-list--child
.ais-HierarchicalMenu__showMore .ais-HierarchicalMenu-showMore
.ais-HierarchicalMenu__noRefinement .ais-HierarchicalMenu--noRefinement

Highlight

See the widget documentation page.

Naming

  • attributeNameattribute

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Highlight No change.
.ais-Highlight__highlighted .ais-Highlight-highlighted
.ais-Highlight__nonHighlighted .ais-Highlight-nonHighlighted

Hits

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Hits__root .ais-Hits

HitsPerPage

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-HitsPerPage__root .ais-HitsPerPage

InfiniteHits

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-InfiniteHits__root .ais-InfiniteHits

See the widget documentation page.

Naming

  • attributeNameattribute
  • limitMinlimit
  • limitMaxshowMoreLimit
  • withSearchBoxsearchable

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Menu__root .ais-Menu
.ais-Menu__items .ais-Menu-list
.ais-Menu__item .ais-Menu-item
.ais-Menu__itemLinkSelected Removed. Use .ais-Menu-item--selected .ais-Menu-link instead.
.ais-Menu__itemLink .ais-Menu-link
.ais-Menu__itemLabelSelected Removed. Use .ais-Menu-item--selected .ais-Menu-label instead.
.ais-Menu__itemLabel .ais-Menu-label
.ais-Menu__itemCount .ais-Menu-count
.ais-Menu__itemCountSelected Removed. Use .ais-Menu-item--selected .ais-Menu-count instead.
.ais-Menu__showMore .ais-Menu-showMore
.ais-Menu__SearchBox .ais-Menu-searchBox
.ais-Menu__noRefinement .ais-Menu--noRefinement

See the widget documentation page.

Naming

  • attributeNameattribute

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-MenuSelect__select .ais-MenuSelect-select
.ais-MenuSelect__option .ais-MenuSelect-option

MultiRange

See the widget documentation page.

Naming

  • Renamed to NumericMenu.

  • attributeNameattribute

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-MultiRange__root .ais-NumericMenu
.ais-MultiRange__items .ais-NumericMenu-list
.ais-MultiRange__item .ais-NumericMenu-item
.ais-MultiRange__itemSelected .ais-NumericMenu-item--selected
.ais-MultiRange__itemLabel .ais-NumericMenu-label
.ais-MultiRange__itemLabelSelected Removed. Use .ais-NumericMenu-item--selected .ais-NumericMenu-label instead.
.ais-MultiRange__itemRadio .ais-NumericMenu-radio
.ais-MultiRange__itemRadioSelected Removed. Use .ais-NumericMenu-item--selected .ais-NumericMenu-radio instead.
.ais-MultiRange__noRefinement .ais-NumericMenu--noRefinement
.ais-MultiRange__itemNoRefinement .ais-NumericMenu-item--noRefinement
.ais-MultiRange__itemAll Removed.

Pagination

See the widget documentation page.

Naming

  • maxPagestotalPages
  • pagesPaddingpadding

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Pagination__root .ais-Pagination
.ais-Pagination__item .ais-Pagination-item
.ais-Pagination__itemFirst .ais-Pagination-item--firstPage
.ais-Pagination__itemPrevious .ais-Pagination-item--previousPage
.ais-Pagination__itemPage .ais-Pagination-item--page
.ais-Pagination__itemNext .ais-Pagination-item--nextPage
.ais-Pagination__itemLast .ais-Pagination-item--lastPage
.ais-Pagination__itemDisabled .ais-Pagination-item--disabled
.ais-Pagination__itemSelected .ais-Pagination-item--selected
.ais-Pagination__itemLink .ais-Pagination-link
.ais-Pagination__noRefinement .ais-Pagination--noRefinement

Panel

See the widget documentation page.

Naming

  • titleheader

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Panel__root .ais-Panel
.ais-Panel__title Removed.
.ais-Panel__noRefinement .ais-Panel--noRefinement

PoweredBy

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-PoweredBy__root .ais-PoweredBy
.ais-PoweredBy__searchBy .ais-PoweredBy-text
.ais-PoweredBy__algoliaLink .ais-PoweredBy-link

RangeInput

See the widget documentation page.

Naming

  • attributeNameattribute

Behavior

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

CSS classes equivalency table

Old class name New class name
.ais-RangeInput__root .ais-RangeInput
.ais-RangeInput__labelMin Removed.
.ais-RangeInput__inputMin .ais-RangeInput-input--min
.ais-RangeInput__separator .ais-RangeInput-separator
.ais-RangeInput__labelMax Removed.
.ais-RangeInput__inputMax .ais-RangeInput-input--max
.ais-RangeInput__submit .ais-RangeInput-submit
.ais-RangeInput__noRefinement .ais-RangeInput--noRefinement

RefinementList

See the widget documentation page.

Naming

  • attributeNameattribute
  • limitMinlimit
  • limitMaxshowMoreLimit
  • withSearchBoxsearchable

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-RefinementList__root .ais-RefinementList
.ais-RefinementList__items .ais-RefinementList-list
.ais-RefinementList__item .ais-RefinementList-item
.ais-RefinementList__itemSelected .ais-RefinementList-item--selected
.ais-RefinementList__itemCheckbox .ais-RefinementList-checkbox
.ais-RefinementList__itemCheckboxSelected Removed. Use .ais-RefinementList-item--selected .ais-RefinementList-checkbox instead.
.ais-RefinementList__itemLabel .ais-RefinementList-label
.ais-RefinementList__itemLabelSelected Removed. Use .ais-RefinementList-item--selected .ais-RefinementList-label instead.
.ais-RefinementList__itemCount .ais-RefinementList-count
.ais-RefinementList__itemCountSelected Removed. Use .ais-RefinementList-item--selected .ais-RefinementList-count instead.
.ais-RefinementList__showMore .ais-RefinementList-showMore
.ais-RefinementList__SearchBox .ais-RefinementList-searchBox
.ais-RefinementList__noRefinement .ais-RefinementList--noRefinement

See the widget documentation page.

Naming

  • submitComponentsubmit
  • resetComponentreset
  • loadingIndicatorComponentloadingIndicator

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-SearchBox__root .ais-SearchBox
.ais-SearchBox__wrapper .ais-SearchBox-form
.ais-SearchBox__input .ais-SearchBox-input
.ais-SearchBox__submit .ais-SearchBox-submit
.ais-SearchBox__reset .ais-SearchBox-reset
.ais-SearchBox__loading-indicator .ais-SearchBox-loadingIndicator

SortBy

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-SortBy__root .ais-SortBy

StarRating

See the widget documentation page.

Naming

  • Renamed to RatingMenu.

  • attributeNameattribute

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-StarRating__root .ais-RatingMenu
.ais-StarRating__ratingLink .ais-RatingMenu-link
.ais-StarRating__ratingLinkSelected Removed. Use .ais-RatingMenu-item--selected .ais-RatingMenu-link instead.
.ais-StarRating__ratingLinkDisabled Removed. Use .ais-RatingMenu-item--disabled .ais-RatingMenu-link instead.
.ais-StarRating__ratingIcon .ais-RatingMenu-starIcon
.ais-StarRating__ratingIconSelected Removed. Use .ais-RatingMenu-item--selected .ais-RatingMenu-starIcon instead.
.ais-StarRating__ratingIconDisabled Removed. Use .ais-RatingMenu-item--disabled .ais-RatingMenu-starIcon instead.
.ais-StarRating__ratingIconEmpty .ais-RatingMenu-starIcon--empty
.ais-StarRating__ratingIconEmptySelected Removed. Use .ais-RatingMenu-item--selected .ais-RatingMenu-starIcon--empty instead.
.ais-StarRating__ratingIconEmptyDisabled Removed. Use .ais-RatingMenu-item--disabled .ais-RatingMenu-starIcon--empty instead.
.ais-StarRating__ratingLabel .ais-RatingMenu-label
.ais-StarRating__ratingLabelSelected Removed. Use .ais-RatingMenu-item--selected .ais-RatingMenu-label instead.
.ais-StarRating__ratingLabelDisabled Removed. Use .ais-RatingMenu-item--disabled .ais-RatingMenu-label instead.
.ais-StarRating__ratingCount .ais-RatingMenu-count
.ais-StarRating__ratingCountSelected Removed. Use .ais-RatingMenu-item--selected .ais-RatingMenu-count instead.
.ais-StarRating__ratingCountDisabled Removed. Use .ais-RatingMenu-item--disabled .ais-RatingMenu-count instead.

Stats

See the widget documentation page.

Naming

  • No change.

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Stats__root .ais-Stats-text

Toggle

See the widget documentation page.

Naming

  • Renamed to ToggleRefinement.

  • attributeNameattribute

Behavior

  • No change.

CSS classes equivalency table

Old class name New class name
.ais-Toggle__root .ais-Toggle
.ais-Toggle__checkbox .ais-Toggle-checkbox
.ais-Toggle__label .ais-Toggle-label

Connectors changes

createConnector

See the connector documentation page.

Naming

  • searchForFacetValuessearchForItems

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

  • limitMinlimit
  • limitMaxshowMoreLimit

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

  • attributeNameattribute
  • limitMinlimit
  • limitMaxshowMoreLimit
  • withSearchBoxsearchable
  • searchForFacetValuessearchForItems

Behavior

  • No change.

connectMultiRange

See the connector documentation page.

Naming

  • Renamed to connectNumericMenu.

  • attributeNameattribute

Behavior

  • No change.

connectPagination

See the connector documentation page.

Naming

  • maxPagestotalPages
  • pagesPaddingpadding

Behavior

  • No change.

connectRange

See the connector documentation page.

Naming

  • attributeNameattribute

Behavior

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

connectRefinementList

See the connector documentation page.

Naming

  • attributeNameattribute
  • limitMinlimit
  • limitMaxshowMoreLimit
  • withSearchBoxsearchable
  • searchForFacetValuessearchForItems

Behavior

  • No change.

connectToggle

See the connector documentation page.

Naming

  • Renamed to connectToggleRefinement.

  • attributeNameattribute

Behavior

  • No change.

Upgrade from v3 to v4

Check out our v4 announcement post

Upgrade from v2 to v3

  • Anytime you are using a connector, when there are no more items in it or no more hits, we will still call your Component. Thus you will have to handle cases like dealing with empty arrays and decide if you want to unmount or hide the widget.

  • Anytime you are using a widget, when there are no more items in it or no more hits, we will still display the widget. You can then decide to hide it with CSS.

Did you find this page helpful?