Guides / Algolia Recommend / Upgrade

Upgrade from Recommend React to React InstantSearch

On this page

The components for displaying recommendations are part of React InstantSearch, starting with version 7.9.0. The Algolia JavaScript API client supports the Recommend API starting with version 4.23.2. With this, you can integrate recommendations seamlessly into your React InstantSearch app, without having to install additional packages.

Packages

Add the react-instantsearch and algoliasearch packages to your project, and remove the @algolia/recommend and @algolia/recommend-js packages:

Copy 
1
2
3
4
5

yarn add algoliasearch react-instantsearch
yarn remove @algolia/recommend-react @algolia/recommend
# or
npm install algoliasearch react-instantsearch
npm uninstall @algolia/recommend-react @algolia/recommend

Imports

Import the Recommend components from React InstantSearch:

Copy 
1
2

- import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
+ import { FrequentlyBoughtTogether } from 'react-instantsearch';

Some imports are no longer available:

  • The <TrendingFacets> component
  • The useTrendingFacets() Hook
  • The useRecommendations() Hook
  • The <Recommend> context provider

For more information, see Components and Hooks.

Usage

Recommend widget must be children of the <InstantSearch> component. Pass the API client and index name to the InstantSearch component:

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

- import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
+ import { InstantSearch, FrequentlyBoughtTogether } from 'react-instantsearch';
- import recommend from '@algolia/recommend';
+ import algoliasearch from 'algoliasearch/lite';

- const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
+ const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

  function App() {
    return (
+     <InstantSearch
+       searchClient={searchClient}
+       indexName="YOUR_INDEX_NAME"
+     >
        <FrequentlyBoughtTogether
-         recommendClient={recommendClient}
-         indexName="YOUR_INDEX_NAME"
          objectIDs={['5723537']}
        />
+     </InstantSearch>
    );
  }

Components

Recommend React React InstantSearch Changes
<FrequentlyBoughtTogether> <FrequentlyBoughtTogether> Prop changes
<RelatedProducts> <RelatedProducts> Prop changes
<TrendingItems> <TrendingItems> Prop changes
<TrendingFacets> Removed Alternative
<LookingSimilar> <LookingSimilar> Prop changes
<Recommend> Removed Alternative

Changes for <FrequentlyBoughtTogether>

Move recommendClient and indexName to <InstantSearch>

The <FrequentlyBoughtTogether> component no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
+ import { InstantSearch, FrequentlyBoughtTogether } from 'react-instantsearch';
- import recommend from '@algolia/recommend';
+ import algoliasearch from 'algoliasearch/lite';

- const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
+ const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 function App() {
   return (
+   <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
      <FrequentlyBoughtTogether
-       recommendClient={recommendClient}
-       indexName="YOUR_INDEX_NAME"
      />
+   </InstantSearch>
  );
}

Replace children and view with the useFrequentlyBoughtTogether() Hook

The <FrequentlyBoughtTogether> component no longer provides children and view props. To fully customize the UI, use the useFrequentlyBoughtTogether() Hook instead.

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

- import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
+ import { useFrequentlyBoughtTogether } from 'react-instantsearch';

  function Recommendations() {
+   const { items } = useFrequentlyBoughtTogether();

    return (
-     <FrequentlyBoughtTogether objectIDs={['5723537']}>
-       <div>{/* … */}</div>
-     </FrequentlyBoughtTogether>
+     <CustomFrequentlyBoughtTogether objectIDs={['5723537']} />
    );
  }

+ function CustomFrequentlyBoughtTogether(props) {
+   const { items } = useFrequentlyBoughtTogether(props);
  
+   return <div>{/* … */}</div>;
+ }

Replace fallbackComponent with emptyComponent

The emptyComponent prop replaces the fallbackComponent prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <FrequentlyBoughtTogether
-     fallbackComponent={() => <p>No recommendations.</p>}
+     emptyComponent={() => <p>No recommendations.</p>}
    />
  );
}

Replace maxRecommendations with limit

The limit prop replaces the maxRecommendations prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <FrequentlyBoughtTogether
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.

Copy 
1
2
3
4
5
6
7

function Recommendations() {
  return (
    <FrequentlyBoughtTogether
-     environment={global}
    />
  );
}

Replace classNames

The classNames keys have changed.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

function Recommendations() {
  return (
    <FrequentlyBoughtTogether
      classNames={{
        root: 'MyCustomFrequentlyBoughtTogether',
+       emptyRoot: 'MyCustomFrequentlyBoughtTogether-emptyRoot',
        title: 'MyCustomFrequentlyBoughtTogether-title',
        container: 'MyCustomFrequentlyBoughtTogether-container',
        list: 'MyCustomFrequentlyBoughtTogether-list',
        item: 'MyCustomFrequentlyBoughtTogether-item',
      }}
    />
  );
}

Changes for <RelatedProducts>

Move recommendClient and indexName to <InstantSearch>

The <RelatedProducts> component no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- import { RelatedProducts } from '@algolia/recommend-react';
+ import { InstantSearch, RelatedProducts } from 'react-instantsearch';
- import recommend from '@algolia/recommend';
+ import algoliasearch from 'algoliasearch/lite';

- const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
+ const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 function App() {
   return (
+   <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
      <RelatedProducts
-       recommendClient={recommendClient}
-       indexName="YOUR_INDEX_NAME"
      />
+   </InstantSearch>
  );
}

Replace children and view with the useRelatedProducts() Hook

The <RelatedProducts> component no longer provides children and view props. To fully customize the UI, use the useRelatedProducts() Hook instead.

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

- import { RelatedProducts } from '@algolia/recommend-react';
+ import { useRelatedProducts } from 'react-instantsearch';

  function Recommendations() {
+   const { items } = useRelatedProducts();

    return (
-     <RelatedProducts objectIDs={['5723537']}>
-       <div>{/* … */}</div>
-     </RelatedProducts>
+     <CustomRelatedProducts objectIDs={['5723537']} />
    );
  }

+ function CustomRelatedProducts(props) {
+   const { items } = useRelatedProducts(props);
  
+   return <div>{/* … */}</div>;
+ }

Replace fallbackComponent with emptyComponent

The emptyComponent prop replaces the fallbackComponent prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <RelatedProducts
-     fallbackComponent={() => <p>No recommendations.</p>}
+     emptyComponent={() => <p>No recommendations.</p>}
    />
  );
}

Replace maxRecommendations with limit

The limit prop replaces the maxRecommendations prop.

The <RelatedProducts> component now takes an optional maxRecommendations prop which replaces limit.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <RelatedProducts
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.

Copy 
1
2
3
4
5
6
7

function Recommendations() {
  return (
    <RelatedProducts
-     environment={global}
    />
  );
}

Replace classNames

The classNames keys have changed.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

function Recommendations() {
  return (
    <RelatedProducts
      classNames={{
        root: 'MyCustomRelatedProducts',
+       emptyRoot: 'MyCustomRelatedProducts-emptyRoot',
        title: 'MyCustomRelatedProducts-title',
        container: 'MyCustomRelatedProducts-container',
        list: 'MyCustomRelatedProducts-list',
        item: 'MyCustomRelatedProducts-item',
      }}
    />
  );
}

Changes for <TrendingItems>

Move recommendClient and indexName to <InstantSearch>

The <TrendingItems> component no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- import { TrendingItems } from '@algolia/recommend-react';
+ import { InstantSearch, TrendingItems } from 'react-instantsearch';
- import recommend from '@algolia/recommend';
+ import algoliasearch from 'algoliasearch/lite';

- const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
+ const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 function App() {
   return (
+   <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
      <TrendingItems
-       recommendClient={recommendClient}
-       indexName="YOUR_INDEX_NAME"
      />
+   </InstantSearch>
  );
}

Replace children and view with the useTrendingItems() Hook

The <TrendingItems> component no longer provides children and view props. To fully customize the UI, use the useTrendingItems() Hook instead.

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

- import { TrendingItems } from '@algolia/recommend-react';
+ import { useTrendingItems } from 'react-instantsearch';

  function Recommendations() {
+   const { items } = useTrendingItems();

    return (
-     <TrendingItems>
-       <div>{/* … */}</div>
-     </TrendingItems>
+     <CustomTrendingItems />
    );
  }

+ function CustomTrendingItems(props) {
+   const { items } = useTrendingItems(props);
  
+   return <div>{/* … */}</div>;
+ }

Replace fallbackComponent with emptyComponent

The emptyComponent prop replaces the fallbackComponent prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <TrendingItems
-     fallbackComponent={() => <p>No recommendations.</p>}
+     emptyComponent={() => <p>No recommendations.</p>}
    />
  );
}

Replace maxRecommendations with limit

The limit prop replaces the maxRecommendations prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <TrendingItems
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.

Copy 
1
2
3
4
5
6
7

function Recommendations() {
  return (
    <TrendingItems
-     environment={global}
    />
  );
}
Replace classNames

The classNames keys have changed.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

function Recommendations() {
  return (
    <TrendingItems
      classNames={{
        root: 'MyCustomTrendingItems',
+       emptyRoot: 'MyCustomTrendingItems-emptyRoot',
        title: 'MyCustomTrendingItems-title',
        container: 'MyCustomTrendingItems-container',
        list: 'MyCustomTrendingItems-list',
        item: 'MyCustomTrendingItems-item',
      }}
    />
  );
}

Alternative for <TrendingFacets>

The <TrendingFacets> component isn’t available in React InstantSearch. If you need it, use the <TrendingFacets> component from the deprecated Recommend React library.

Changes for <LookingSimilar>

Move recommendClient and indexName to <InstantSearch>

The <LookingSimilar> component no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

- import { LookingSimilar } from '@algolia/recommend-react';
+ import { InstantSearch, LookingSimilar } from 'react-instantsearch';
- import recommend from '@algolia/recommend';
+ import algoliasearch from 'algoliasearch/lite';

- const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
+ const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

 function App() {
   return (
+   <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
      <LookingSimilar
-       recommendClient={recommendClient}
-       indexName="YOUR_INDEX_NAME"
      />
+   </InstantSearch>
  );
}

Replace children and view with the useLookingSimilar() Hook

The <LookingSimilar> component no longer provides children and view props. To fully customize the UI, use the useLookingSimilar() Hook instead.

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

- import { LookingSimilar } from '@algolia/recommend-react';
+ import { useLookingSimilar } from 'react-instantsearch';

  function Recommendations() {
+   const { items } = useLookingSimilar();

    return (
-     <LookingSimilar objectIDs={['5723537']}>
-       <div>{/* … */}</div>
-     </LookingSimilar>
+     <CustomLookingSimilar objectIDs={['5723537']} />
    );
  }

+ function CustomLookingSimilar(props) {
+   const { items } = useLookingSimilar(props);
  
+   return <div>{/* … */}</div>;
+ }

Replace fallbackComponent with emptyComponent

The emptyComponent prop replaces the fallbackComponent prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <LookingSimilar
-     fallbackComponent={() => <p>No recommendations.</p>}
+     emptyComponent={() => <p>No recommendations.</p>}
    />
  );
}

Replace maxRecommendations with limit

The limit prop replaces the maxRecommendations prop.

Copy 
1
2
3
4
5
6
7
8

function Recommendations() {
  return (
    <LookingSimilar
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.

Copy 
1
2
3
4
5
6
7

function Recommendations() {
  return (
    <LookingSimilar
-     environment={global}
    />
  );
}

Replace classNames

The classNames keys have changed.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

function Recommendations() {
  return (
    <LookingSimilar
      classNames={{
        root: 'MyCustomLookingSimilar',
+       emptyRoot: 'MyCustomLookingSimilar-emptyRoot',
        title: 'MyCustomLookingSimilar-title',
        container: 'MyCustomLookingSimilar-container',
        list: 'MyCustomLookingSimilar-list',
        item: 'MyCustomLookingSimilar-item',
      }}
    />
  );
}

Hooks

Recommend React React InstantSearch Changes
useFrequentlyBoughtTogether() useFrequentlyBoughtTogether() Prop changes
useRelatedProducts() useRelatedProducts() Prop changes
useTrendingItems() useTrendingItems() Prop changes
useTrendingFacets() Removed Alternative
useLookingSimilar() useLookingSimilar() Prop changes
useRecommendations() Removed Alternative

Changes for useFrequentlyBoughtTogether()

Move recommendClient and indexName to <InstantSearch>

The useFrequentlyBoughtTogether() Hook no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

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

 - import { useFrequentlyBoughtTogether } from '@algolia/recommend-react';
 + import { InstantSearch, useFrequentlyBoughtTogether } from 'react-instantsearch';
 - import recommend from '@algolia/recommend';
 + import algoliasearch from 'algoliasearch/lite';

 - const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
 + const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

  function App() {
    return (
 +    <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
        <CustomFrequentlyBoughtTogether />
 +    </InstantSearch>
    );
 }

 function CustomFrequentlyBoughtTogether() {
  const { items } = useFrequentlyBoughtTogether({
-   recommendClient={recommendClient}
-   indexName="YOUR_INDEX_NAME"
  });
 }

Replace recommendations with items

The useFrequentlyBoughtTogether() Hook returns recommendations under the items key instead of recommendations.

Copy 
1
2
3
4
5
6

 function CustomFrequentlyBoughtTogether() {
  const {
-   recommendations
+   items
  } = useFrequentlyBoughtTogether();
 }

Changes for useRelatedProducts()

Move recommendClient and indexName to <InstantSearch>

The useRelatedProducts() Hook no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

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

 - import { useRelatedProducts } from '@algolia/recommend-react';
 + import { InstantSearch, useRelatedProducts } from 'react-instantsearch';
 - import recommend from '@algolia/recommend';
 + import algoliasearch from 'algoliasearch/lite';

 - const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
 + const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

  function App() {
    return (
 +    <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
        <CustomRelatedProducts />
 +    </InstantSearch>
    );
 }

 function CustomRelatedProducts() {
  const { items } = useRelatedProducts({
-   recommendClient={recommendClient}
-   indexName="YOUR_INDEX_NAME"
  });
 }

Replace recommendations with items

The useRelatedProducts() Hook returns recommendations under the items key instead of recommendations.

Copy 
1
2
3
4
5
6

 function CustomRelatedProducts() {
  const {
-   recommendations
+   items
  } = useRelatedProducts();
 }

Changes for useTrendingItems()

Move recommendClient and indexName to <InstantSearch>

The useTrendingItems() Hook no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

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

 - import { useTrendingItems } from '@algolia/recommend-react';
 + import { InstantSearch, useTrendingItems } from 'react-instantsearch';
 - import recommend from '@algolia/recommend';
 + import algoliasearch from 'algoliasearch/lite';

 - const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
 + const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

  function App() {
    return (
 +    <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
        <CustomTrendingItems />
 +    </InstantSearch>
    );
 }

 function CustomTrendingItems() {
  const { items } = useTrendingItems({
-   recommendClient={recommendClient}
-   indexName="YOUR_INDEX_NAME"
  });
 }

Replace recommendations with items

The useTrendingItems() Hook returns recommendations under the items key instead of recommendations.

Copy 
1
2
3
4
5
6

 function CustomTrendingItems() {
  const {
-   recommendations
+   items
  } = useTrendingItems();
 }

Alternative for useTrendingFacets()

The useTrendingFacets() Hook isn’t available in React InstantSearch. If you need it, use the useTrendingFacets() Hook from the deprecated Recommend React library.

Alternative for useRecommendations()

The useRecommendations() Hook isn’t available in React InstantSearch. Instead, use the dedicated Hooks for each Recommend model.

Changes for useLookingSimilar()

Move recommendClient and indexName to <InstantSearch>

The useLookingSimilar() Hook no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to <InstantSearch>.

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

 - import { useLookingSimilar } from '@algolia/recommend-react';
 + import { InstantSearch, useLookingSimilar } from 'react-instantsearch';
 - import recommend from '@algolia/recommend';
 + import algoliasearch from 'algoliasearch/lite';

 - const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
 + const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

  function App() {
    return (
 +    <InstantSearch searchClient={searchClient} indexName="YOUR_INDEX_NAME">
        <CustomLookingSimilar />
 +    </InstantSearch>
    );
 }

 function CustomLookingSimilar() {
  const { items } = useLookingSimilar({
-   recommendClient={recommendClient}
-   indexName="YOUR_INDEX_NAME"
  });
 }

Replace recommendations with items

The useLookingSimilar() Hook returns recommendations under the items key instead of recommendations.

Copy 
1
2
3
4
5
6

 function CustomLookingSimilar() {
  const {
-   recommendations
+   items
  } = useLookingSimilar();
 }

Remove <Recommend> context provider

The <Recommend> context provider is no longer necessary to batch requests. Remove it from your implementation.

Copy 
1
2
3
4
5
6
7
8
9

- import { Recommend } from '@algolia/recommend-react';

  function App() {
    return (
-     <Recommend recommendClient={recommendClient}>
        {/* … */}
-     </Recommend>
    );
  }

HorizontalSlider

To use a HorizontalSlider component in your Recommend components, use the Hook for the Recommend model, such as useFrequentlyBoughtTogether() to customize the components.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import algoliasearch from 'algoliasearch/lite';
import { InstantSearch } from 'react-instantsearch';

import { CustomFrequentlyBoughtTogether } from './CustomFrequentlyBoughtTogether';

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

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="YOUR_INDEX_NAME"
    >
      <CustomFrequentlyBoughtTogether objectIDs={['5723537']} />
    </InstantSearch>
  );
}
Previous
Recommend JS
Did you find this page helpful?