Skip to main content
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:
npm install algoliasearch react-instantsearch
npm uninstall @algolia/recommend-react @algolia/recommend

Imports

Import the Recommend components from React InstantSearch:
React
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:
React
- 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
+ const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

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

Components

Recommend ReactReact InstantSearchChanges
FrequentlyBoughtTogetherFrequentlyBoughtTogetherProp changes
RelatedProductsRelatedProductsProp changes
TrendingItemsTrendingItemsProp changes
TrendingFacetsRemovedAlternative
LookingSimilarLookingSimilarProp changes
RecommendRemovedAlternative

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.
React
- 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
+ const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

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

Replace children and view with the layoutComponent prop or the useFrequentlyBoughtTogether Hook

The FrequentlyBoughtTogether component no longer provides children and view props. To fully customize the UI, use either the layoutComponent prop or the useFrequentlyBoughtTogether Hook instead.
Layout
import { FrequentlyBoughtTogether } from '@algolia/recommend-react';

  function Recommendations() {
    return (
      <FrequentlyBoughtTogether
        objectIDs={['5723537']}
-       layoutComponent={() => <div>{/* … */}</div>}
-     />

-       <div>{/* … */}</div>
-     </FrequentlyBoughtTogether>
    );
  }
Hook
- 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.
React
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.
React
function Recommendations() {
  return (
    <FrequentlyBoughtTogether
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.
React
function Recommendations() {
  return (
    <FrequentlyBoughtTogether
-     environment={global}
    />
  );
}

Replace classNames

The classNames keys have changed.
React
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>.
React
- 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
+ const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

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

Replace children and view with the layoutComponent prop or the useRelatedProducts() Hook

The RelatedProducts component no longer provides children and view props. To fully customize the UI, use either the layoutComponent prop or the useRelatedProducts Hook instead.
Layout
import { RelatedProducts } from '@algolia/recommend-react';

  function Recommendations() {
    return (
      <RelatedProducts
        objectIDs={['5723537']}

-       layoutComponent={() => <div>{/* … */}</div>}
-     />

-       <div>{/* … */}</div>
-     </RelatedProducts>
    );
  }

Hook
- 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.
React
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.
React
function Recommendations() {
  return (
    <RelatedProducts
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.
React
function Recommendations() {
  return (
    <RelatedProducts
-     environment={global}
    />
  );
}

Replace classNames

The classNames keys have changed.
React
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.
React
- 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
+ const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

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

Replace children and view with the layoutComponent prop or the useTrendingItems() Hook

The TrendingItems component no longer provides children and view props. To fully customize the UI, use either the layoutComponent prop or the useTrendingItems Hook instead.
Layout
import { TrendingItems } from '@algolia/recommend-react';

  function Recommendations() {
    return (
      <TrendingItems

-       layoutComponent={() => <div>{/* … */}</div>}
-     />

-       <div>{/* … */}</div>
-     </TrendingItems>
    );
  }

Hook
- 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.
React
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.
React
function Recommendations() {
  return (
    <TrendingItems
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.
React
function Recommendations() {
  return (
    <TrendingItems
-     environment={global}
    />
  );
}
Replace classNames
The classNames keys have changed.
React
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.
React
- 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
+ const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

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

Replace children and view with the layoutComponent prop or the useLookingSimilar() Hook

The LookingSimilar component no longer provides children and view props. To fully customize the UI, use either the layoutComponent prop or the useLookingSimilar Hook instead.
Layout
import { LookingSimilar } from '@algolia/recommend-react';

  function Recommendations() {
    return (
      <LookingSimilar
        objectIDs={['5723537']}

-       layoutComponent={() => <div>{/* … */}</div>}
-     />

-       <div>{/* … */}</div>
-     </LookingSimilar>
    );
  }

Hook
- 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.
React
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.
React
function Recommendations() {
  return (
    <LookingSimilar
-     maxRecommendations={3}
+     limit={3}
    />
  );
}

Remove environment

The environment prop is no longer needed.
React
function Recommendations() {
  return (
    <LookingSimilar
-     environment={global}
    />
  );
}

Replace classNames

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

Hooks

Recommend ReactReact InstantSearchChanges
useFrequentlyBoughtTogetheruseFrequentlyBoughtTogetherProp changes
useRelatedProductsuseRelatedProductsProp changes
useTrendingItemsuseTrendingItemsProp changes
useTrendingFacetsRemovedAlternative
useLookingSimilaruseLookingSimilarProp changes
useRecommendationsRemovedAlternative

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.
React
 - 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
 + const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

  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.
React
 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.
React
 - 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
 + const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

  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.
React
 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.
React
 - 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
 + const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

  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.
React
 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.
React
 - 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('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');
 + const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

  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.
React
 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.
React
- import { Recommend } from '@algolia/recommend-react';

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

HorizontalSlider

The HorizontalSlider component is now available in React InstantSearch as the Carousel component. For Carousel props, check the API reference:
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, FrequentlyBoughtTogether, Carousel } from 'react-instantsearch';

const searchClient = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_SEARCH_API_KEY');

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="YOUR_INDEX_NAME"
    >
      <FrequentlyBoughtTogether
        objectIDs={['5723537']}
        layoutComponent={Carousel}
      />
    </InstantSearch>
  );
}
I