Guides / Building Search UI

Jan. 20, 2022

Upgrading React 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 the following breaking changes were introduced:

Server-side rendered (SSR) API

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

Support was added 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.

Copy
// 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} />);

  // ...
});

Copy
// 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')
);

Copy
// 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 preceding server and browser modules. The declaration of indexName and searchClient was duplicated. You can avoid this with a createApp function that returns the App and the props that you must provide. You can find this pattern applied inside the complete SSR example.

Removed support for `appId` and `apiKey`

Reach InstantSearch no longer supports 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 since algoliasearch is no longer shipped with React InstantSearch, you can use any SearchClient you want to use.

Copy
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 doesn’t render anything.

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

Copy
// ...

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 detailed change log of the package.

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:

Copy
// 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:

Copy

1
yarn remove react-instantsearch

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

Copy

1
yarn add react-instantsearch-dom

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

Copy
// 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:

Copy

1
yarn remove react-instantsearch

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

Copy

1
yarn add react-instantsearch-native

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

Copy
// 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';

</section>

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

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:

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:

Copy
<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

It’s strongly recommended to use at least reset.css to avoid the visual side effects induced by the new semantic changes made on most widgets.

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.

Copy
<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.

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

limitMin → limit
limitMax → showMoreLimit

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

attributeName → attribute

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`
`.ais-InfiniteHits__loadMore`	`.ais-InfiniteHits-loadMore`

See the widget documentation page.

Naming

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

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`

MenuSelect

See the widget documentation page.

Naming

attributeName → attribute

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.
attributeName → attribute

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

maxPages → totalPages
pagesPadding → padding

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

title → header

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

attributeName → attribute

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

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

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

submitComponent → submit
resetComponent → reset
loadingIndicatorComponent → loadingIndicator

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.
attributeName → attribute

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.
attributeName → attribute

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

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 the 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, your component will still be called. Thus you will have to handle cases like dealing with empty arrays and decide if you want to hide the widget.
Anytime you are using a widget, when there are no more items in it or no more hits, the widget will still be displayed. You can then decide to hide it with CSS.

Upgrade guides

Widgets showcase

Did you find this page helpful?

Upgrading React InstantSearch

On this page

Upgrade from v5 to v6

Server-side rendered (SSR) API

Removed support for appId and apiKey

Removed support for root in InstantSearch and Index

algoliasearch-helper 3.x.x

Package imports since 5.2.0

Migration for React DOM

Migration for React Native

Upgrade from v4 to v5

Migration steps

Updating widget & connector names

Updating prop names

Removing deprecation

Updating styles

Adding className

Widgets changes

InstantSearch

Breadcrumb

ClearAll

CurrentRefinements

HierarchicalMenu

Highlight

Hits

HitsPerPage

InfiniteHits

Menu

MenuSelect

MultiRange

Pagination

Panel

PoweredBy

RangeInput

RefinementList

SortBy

StarRating

Stats

Toggle

Connectors changes

createConnector

connectCurrentRefinements

connectHierarchicalMenu

connectHighlight

connectMenu

connectMultiRange

connectPagination

connectRange

connectRefinementList

connectToggle

Upgrade from v3 to v4

Upgrade from v2 to v3

On this page

Removed support for `appId` and `apiKey`

Removed support for `root` in `InstantSearch` and `Index`

`algoliasearch-helper` 3.x.x