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:
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:
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:
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>
.
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 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
1
2
3
4
5
6
7
8
9
10
11
12
import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
function Recommendations() {
return (
<FrequentlyBoughtTogether
objectIDs={['5723537']}
+ layoutComponent={() => <div>{/* … */}</div>}
+ />
- <div>{/* … */}</div>
- </FrequentlyBoughtTogether>
);
}
Hook
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.
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.
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.
1
2
3
4
5
6
7
function Recommendations() {
return (
<FrequentlyBoughtTogether
- environment={global}
/>
);
}
Replace classNames
The classNames
keys have changed.
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>
.
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 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
1
2
3
4
5
6
7
8
9
10
11
12
import { RelatedProducts } from '@algolia/recommend-react';
function Recommendations() {
return (
<RelatedProducts
objectIDs={['5723537']}
+ layoutComponent={() => <div>{/* … */}</div>}
+ />
- <div>{/* … */}</div>
- </RelatedProducts>
);
}
Hook
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.
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
.
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.
1
2
3
4
5
6
7
function Recommendations() {
return (
<RelatedProducts
- environment={global}
/>
);
}
Replace classNames
The classNames
keys have changed.
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>
.
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 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
1
2
3
4
5
6
7
8
9
10
11
import { TrendingItems } from '@algolia/recommend-react';
function Recommendations() {
return (
<TrendingItems
+ layoutComponent={() => <div>{/* … */}</div>}
+ />
- <div>{/* … */}</div>
- </TrendingItems>
);
}
Hook
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.
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.
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.
1
2
3
4
5
6
7
function Recommendations() {
return (
<TrendingItems
- environment={global}
/>
);
}
Replace classNames
The classNames
keys have changed.
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>
.
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 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
1
2
3
4
5
6
7
8
9
10
11
12
import { LookingSimilar } from '@algolia/recommend-react';
function Recommendations() {
return (
<LookingSimilar
objectIDs={['5723537']}
+ layoutComponent={() => <div>{/* … */}</div>}
+ />
- <div>{/* … */}</div>
- </LookingSimilar>
);
}
Hook
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.
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.
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.
1
2
3
4
5
6
7
function Recommendations() {
return (
<LookingSimilar
- environment={global}
/>
);
}
Replace classNames
The classNames
keys have changed.
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>
.
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
.
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>
.
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
.
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>
.
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
.
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>
.
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
.
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.
1
2
3
4
5
6
7
8
9
- 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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, FrequentlyBoughtTogether, Carousel } from 'react-instantsearch';
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
function App() {
return (
<InstantSearch
searchClient={searchClient}
indexName="YOUR_INDEX_NAME"
>
<FrequentlyBoughtTogether
objectIDs={['5723537']}
layoutComponent={Carousel}
/>
</InstantSearch>
);
}