Upgrade from Recommend JS to InstantSearch.js

The widgets for displaying recommendations are part of InstantSearch.js, starting with version 4.69.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 InstantSearch app, without having to install additional packages.

Packages

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

npm install algoliasearch instantsearch.js
npm uninstall @algolia/recommend-js @algolia/recommend

Imports

Import the Recommend widgets from InstantSearch.js:

JavaScript

import { frequentlyBoughtTogether } from '@algolia/recommend-js'; 
import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets'; 

The trendingFacets function is no longer available. To replace it, see widgets.

Usage

Add the Recommend widgets to the instantsearch component. Pass the API client and index name to the instantsearch widget:

JavaScript

- import { frequentlyBoughtTogether } from '@algolia/recommend-js';
+ import instantsearch from 'instantsearch.js';
+ import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';
- 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');

+ const search = instantsearch({
+  searchClient,
+  indexName: 'YOUR_INDEX_NAME',
+ }).addWidgets([
    frequentlyBoughtTogether({
      container: '#frequentlyBoughtTogether',
-     recommendClient,
-     indexName: 'YOUR_INDEX_NAME',
      objectIDs: ['5723537'],
    });
+ ]);
+ search.start();

Widgets

Recommend JS	InstantSearch.js	Changes
`frequentlyBoughtTogether`	`frequentlyBoughtTogether`	Prop changes
`relatedProducts`	`relatedProducts`	Prop changes
`trendingItems`	`trendingItems`	Prop changes
`trendingFacets`	Removed	Alternative
`lookingSimilar`	`lookingSimilar`	Prop changes

Changes for `frequentlyBoughtTogether`

Move `recommendClient` and `indexName` to `instantsearch`

The frequentlyBoughtTogether widget no longer needs recommendClient and indexName props. Instead, pass a searchClient and the ìndexName to instantsearch.

JavaScript

- import { frequentlyBoughtTogether } from '@algolia/recommend-js';
+ import instantsearch from 'instantsearch.js';
+ import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';
- 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');

+ const search = instantsearch({
+  searchClient,
+  indexName: 'YOUR_INDEX_NAME',
+ }).addWidgets([
    frequentlyBoughtTogether({
      container: '#frequentlyBoughtTogether',
-     recommendClient,
-     indexName: 'YOUR_INDEX_NAME',
      objectIDs: ['5723537'],
    });
+ ]);
+ search.start();

Replace `view` with the `layout` template or the `connectFrequentlyBoughtTogether` connector

The frequentlyBoughtTogether widget no longer provides a view prop. To fully customize the UI, use either the layout template or the connectFrequentlyBoughtTogether connector instead.

Layout template

JavaScript

- import { frequentlyBoughtTogether } from '@algolia/recommend-js';
+ import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';

  frequentlyBoughtTogether({
    container: '#frequentlyBoughtTogether',
-   view: (props) => { /* ... */ },
+   templates: {
+     layout({ items }, { html }) {
+       // …
+     },
+   }
  });

Connector

JavaScript

- import { frequentlyBoughtTogether } from '@algolia/recommend-js';
+ import {
+   connectFrequentlyBoughtTogether,
+ } from 'instantsearch.js/es/connectors';

+ const customFrequentlyBoughtTogether = connectFrequentlyBoughtTogether(({ items, widgetParams }) => {
+   const container = document.querySelector(widgetParams.container);
+   container.innerHTML = `/* ... */`;
+ });

- frequentlyBoughtTogether({
+ customFrequentlyBoughtTogether({
    container: '#frequentlyBoughtTogether',
-   view: (props) => { /* ... */ },
  }),

Replace component props with `templates`

The frequentlyBoughtTogether widget uses templates to customize specific parts of its UI.

Recommend JS	InstantSearch.js
`headerComponent`	`header`
`itemComponent`	`item`
`fallbackComponent`	`empty`

frequentlyBoughtTogether({
- headerComponent({ classNames, recommendations, html }) {
-   return html`<h2 class=${classNames.title}>
-     Recommendations (${recommendations.length})
-   </h2>`;
- },
+ templates: {
+   header({ cssClasses, items }, { html }) {
+     return html`<h2 class=${cssClasses.title}>
+       Recommendations (${items.length})
+     </h2>`;
+   }
+ },
});

Replace `translations` with `templates`

The frequentlyBoughtTogether widget uses templates to provide translations to the header.

JavaScript

frequentlyBoughtTogether({
- translations: {
-   title: 'Recommendations',
- },
+ templates: {
+   header: ({ cssClasses }, { html }) {
+     return html`<h2 class=${cssClasses.title}>Recommendations</h2>`;
+   },
+ },
});

Replace `maxRecommendations` with `limit`

The limit prop replaces the maxRecommendations prop.

JavaScript

frequentlyBoughtTogether({
- maxRecommendations: 3,
+ limit: 3,
});

Remove `environment`

The environment prop is no longer needed.

JavaScript

frequentlyBoughtTogether({
- environment: global,
});

Replace `classNames` with `cssClasses`

The cssClasses prop replaces the classNames prop.

JavaScript

frequentlyBoughtTogether({
- classNames: {
+ cssClasses: {
    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 widget no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to instantsearch.

JavaScript

- import { relatedProducts } from '@algolia/recommend-js';
+ import instantsearch from 'instantsearch.js';
+ import { relatedProducts } from 'instantsearch.js/es/widgets';
- 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');

+ const search = instantsearch({
+  searchClient,
+  indexName: 'YOUR_INDEX_NAME',
+ }).addWidgets([
    relatedProducts({
      container: '#relatedProducts',
-     recommendClient,
-     indexName: 'YOUR_INDEX_NAME',
      objectIDs: ['5723537'],
    });
+ ]);
+ search.start();

Replace `view` with the `layout` template or the `connectRelatedProducts` connector

The relatedProducts widget no longer provides a view prop. To fully customize the UI, use either the layout template or the connectRelatedProducts connector instead.

Layout template

JavaScript

- import { relatedProducts } from '@algolia/recommend-js';
+ import { relatedProducts } from 'instantsearch.js/es/widgets';

  relatedProducts({
    container: '#relatedProducts',
-   view: (props) => { /* ... */ },
+   templates: {
+     layout({ items }, { html }) {
+       // …
+     },
+   }
  });

Connector

JavaScript

- import { relatedProducts } from '@algolia/recommend-js';
+ import {
+   connectRelatedProducts,
+ } from 'instantsearch.js/es/connectors';

+ const customRelatedProducts = connectRelatedProducts(({ items, widgetParams }) => {
+   const container = document.querySelector(widgetParams.container);
+   container.innerHTML = `/* ... */`;
+ });

- relatedProducts({
+ customRelatedProducts({
    container: '#relatedProducts',
-   view: (props) => { /* ... */ },
  }),

Replace component props with `templates`

The relatedProducts widget uses templates to customize specific parts of its UI.

Recommend JS	InstantSearch.js
`headerComponent`	`header`
`itemComponent`	`item`
`fallbackComponent`	`empty`

relatedProducts({
- headerComponent({ classNames, recommendations, html }) {
-   return html`<h2 class=${classNames.title}>
-     Recommendations (${recommendations.length})
-   </h2>`;
- },
+ templates: {
+   header({ cssClasses, items }, { html }) {
+     return html`<h2 class=${cssClasses.title}>
+       Recommendations (${items.length})
+     </h2>`;
+   }
+ },
});

Replace `translations` with `templates`

The relatedProducts widget uses templates to provide translations to the header.

JavaScript

relatedProducts({
- translations: {
-   title: 'Recommendations',
- },
+ templates: {
+   header: ({ cssClasses }, { html }) {
+     return html`<h2 class=${cssClasses.title}>Recommendations</h2>`;
+   },
+ },
});

Replace `maxRecommendations` with `limit`

The limit prop replaces the maxRecommendations prop.

JavaScript

relatedProducts({
- maxRecommendations: 3,
+ limit: 3,
});

Remove `environment`

The environment prop is no longer needed.

JavaScript

relatedProducts({
- environment: global,
});

Replace `classNames` with `cssClasses`

The cssClasses prop replaces the classNames prop.

JavaScript

relatedProducts({
- classNames: {
+ cssClasses: {
    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 widget no longer needs recommendClient and indexName props. Instead, pass a searchClient and the ìndexName to instantsearch.

JavaScript

- import { trendingItems } from '@algolia/recommend-js';
+ import instantsearch from 'instantsearch.js';
+ import { trendingItems } from 'instantsearch.js/es/widgets';
- 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');

+ const search = instantsearch({
+  searchClient,
+  indexName: 'YOUR_INDEX_NAME',
+ }).addWidgets([
    trendingItems({
      container: '#trendingItems',
-     recommendClient,
-     indexName: 'YOUR_INDEX_NAME',
    });
+ ]);
+ search.start();

Replace `view` with the `layout` template or the `connectTrendingItems` connector

The trendingItems widget no longer provides a view prop. To fully customize the UI, use either the layout template or the connectTrendingItems connector instead.

Layout template

JavaScript

- import { trendingItems } from '@algolia/recommend-js';
+ import { trendingItems } from 'instantsearch.js/es/widgets';

  trendingItems({
    container: '#trendingItems',
-   view: (props) => { /* ... */ },
+   templates: {
+     layout({ items }, { html }) {
+       // …
+     },
+   }
  });

Connector

JavaScript

- import { trendingItems } from '@algolia/recommend-js';
+ import {
+   connectTrendingItems,
+ } from 'instantsearch.js/es/connectors';

+ const customTrendingItems = connectTrendingItems(({ items, widgetParams }) => {
+   const container = document.querySelector(widgetParams.container);
+   container.innerHTML = `/* ... */`;
+ });

- trendingItems({
+ customTrendingItems({
    container: '#trendingItems',
-   view: (props) => { /* ... */ },
  }),

Replace component props with templates

The trendingItems widget uses templates to customize specific parts of its UI.

Recommend JS	InstantSearch.js
`headerComponent`	`header`
`itemComponent`	`item`
`fallbackComponent`	`empty`

trendingItems({
- headerComponent({ classNames, recommendations, html }) {
-   return html`<h2 class=${classNames.title}>
-     Recommendations (${recommendations.length})
-   </h2>`;
- },
+ templates: {
+   header({ cssClasses, items }, { html }) {
+     return html`<h2 class=${cssClasses.title}>
+       Recommendations (${items.length})
+     </h2>`;
+   }
+ },
});

Replace `translations` with `templates`

The trendingItems widget uses templates to provide translations to the header.

JavaScript

trendingItems({
- translations: {
-   title: 'Recommendations',
- },
+ templates: {
+   header: ({ cssClasses }, { html }) {
+     return html`<h2 class=${cssClasses.title}>Recommendations</h2>`;
+   },
+ },
});

Replace `maxRecommendations` with `limit`

The limit prop replaces the maxRecommendations prop.

JavaScript

trendingItems({
- maxRecommendations: 3,
+ limit: 3,
});

Remove `environment`

The environment prop is no longer needed.

JavaScript

trendingItems({
- environment: global,
});

Replace `classNames` with `cssClasses`

The cssClasses prop replaces the classNames prop.

JavaScript

trendingItems({
- classNames: {
+ cssClasses: {
    root: 'MyCustomTrendingItems',
+   emptyRoot: 'MyCustomTrendingItems-emptyRoot',
    title: 'MyCustomTrendingItems-title',
    container: 'MyCustomTrendingItems-container',
    list: 'MyCustomTrendingItems-list',
    item: 'MyCustomTrendingItems-item',
  },
});

Alternative for `trendingFacets`

InstantSearch.js doesn’t include a widget for trendingFacets. If you need it, use the trendingFacets function from the deprecated Recommend JS library.

Changes for `lookingSimilar`

Move recommendClient and indexName to instantsearch

The lookingSimilar widget no longer needs recommendClient and indexName props. Instead, pass a searchChlient and the ìndexName to instantsearch.

JavaScript

- import { lookingSimilar } from '@algolia/recommend-js';
+ import instantsearch from 'instantsearch.js';
+ import { lookingSimilar } from 'instantsearch.js/es/widgets';
- 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');

+ const search = instantsearch({
+  searchClient,
+  indexName: 'YOUR_INDEX_NAME',
+ }).addWidgets([
    lookingSimilar({
      container: '#lookingSimilar',
-     recommendClient,
-     indexName: 'YOUR_INDEX_NAME',
      objectIDs: ['5723537'],
    });
+ ]);
+ search.start();

Replace `view` with the `layout` template or the `connectLookingSimilar` connector

The lookingSimilar widget no longer provides a view prop. To fully customize the UI, use either the layout template or the connectLookingSimilar connector instead.

Layout template

JavaScript

- import { lookingSimilar } from '@algolia/recommend-js';
+ import { lookingSimilar } from 'instantsearch.js/es/widgets';

  lookingSimilar({
    container: '#lookingSimilar',
-   view: (props) => { /* ... */ },
+   templates: {
+     layout({ items }, { html }) {
+       // …
+     },
+   }
  });

Connector

JavaScript

- import { lookingSimilar } from '@algolia/recommend-js';
+ import {
+   connectLookingSimilar,
+ } from 'instantsearch.js/es/connectors';

+ const customLookingSimilar = connectLookingSimilar(({ items, widgetParams }) => {
+   const container = document.querySelector(widgetParams.container);
+   container.innerHTML = `/* ... */`;
+ });

- lookingSimilar({
+ customLookingSimilar({
    container: '#lookingSimilar',
-   view: (props) => { /* ... */ },
  }),

Replace component props with `templates`

The lookingSimilar widget uses templates to customize specific parts of its UI.

Recommend JS	InstantSearch.js
`headerComponent`	`header`
`itemComponent`	`item`
`fallbackComponent`	`empty`

lookingSimilar({
- headerComponent({ classNames, recommendations, html }) {
-   return html`<h2 class=${classNames.title}>
-     Recommendations (${recommendations.length})
-   </h2>`;
- },
+ templates: {
+   header({ cssClasses, items }, { html }) {
+     return html`<h2 class=${cssClasses.title}>
+       Recommendations (${items.length})
+     </h2>`;
+   }
+ },
});

Replace translations with `templates`

The lookingSimilar widget uses templates to provide translations to the header.

JavaScript

lookingSimilar({
- translations: {
-   title: 'Recommendations',
- },
+ templates: {
+   header: ({ cssClasses }, { html }) {
+     return html`<h2 class=${cssClasses.title}>Recommendations</h2>`;
+   },
+ },
});

Replace `maxRecommendations` with `limit`

The limit prop replaces the maxRecommendations prop.

JavaScript

lookingSimilar({
- maxRecommendations: 3,
+ limit: 3,
});

Remove `environment`

The environment prop is no longer needed.

JavaScript

lookingSimilar({
  environment: global, 
});

Replace `classNames` with `cssClasses`

The classNames keys have changed and are defined through the cssClasses prop.

JavaScript

lookingSimilar({
- classNames: {
+ cssClasses: {
    root: 'MyCustomLookingSimilar',
+   emptyRoot: 'MyCustomLookingSimilar-emptyRoot',
    title: 'MyCustomLookingSimilar-title',
    container: 'MyCustomLookingSimilar-container',
    list: 'MyCustomLookingSimilar-list',
    item: 'MyCustomLookingSimilar-item',
  },
});

`horizontalSlider`

The horizontalSlider view is now available in InstantSearch.js as a carousel template. For carousel options, check the API reference:

JavaScript

import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';
import { carousel } from 'instantsearch.js/es/templates';

frequentlyBoughtTogether({
  // ...
  templates: {
    layout: carousel(),
  },
});

Guides

​Packages

​Imports

​Usage

​Widgets

​Changes for frequentlyBoughtTogether

​Move recommendClient and indexName to instantsearch

​Replace view with the layout template or the connectFrequentlyBoughtTogether connector

Layout template

Connector

​Replace component props with templates

​Replace translations with templates

​Replace maxRecommendations with limit

​Remove environment

​Replace classNames with cssClasses

​Changes for relatedProducts

​Move recommendClient and indexName to instantsearch

​Replace view with the layout template or the connectRelatedProducts connector

Layout template

Connector

​Replace component props with templates

​Replace translations with templates

​Replace maxRecommendations with limit

​Remove environment

​Replace classNames with cssClasses

​Changes for trendingItems

​Move recommendClient and indexName to instantsearch

​Replace view with the layout template or the connectTrendingItems connector

Layout template

Connector

​Replace component props with templates

​Replace translations with templates

​Replace maxRecommendations with limit

​Remove environment

​Replace classNames with cssClasses

​Alternative for trendingFacets

​Changes for lookingSimilar

​Move recommendClient and indexName to instantsearch

​Replace view with the layout template or the connectLookingSimilar connector

Layout template

Connector

​Replace component props with templates

​Replace translations with templates

​Replace maxRecommendations with limit

​Remove environment

Replace classNames with cssClasses

​horizontalSlider

Packages

Imports

Usage

Widgets

Changes for `frequentlyBoughtTogether`

Move `recommendClient` and `indexName` to `instantsearch`

Replace `view` with the `layout` template or the `connectFrequentlyBoughtTogether` connector

Replace component props with `templates`

Replace `translations` with `templates`

Replace `maxRecommendations` with `limit`

Remove `environment`

Replace `classNames` with `cssClasses`

Changes for `relatedProducts`

Move `recommendClient` and `indexName` to `instantsearch`

Replace `view` with the `layout` template or the `connectRelatedProducts` connector

Replace component props with `templates`

Replace `translations` with `templates`

Replace `maxRecommendations` with `limit`

Remove `environment`

Replace `classNames` with `cssClasses`

Changes for `trendingItems`

Move `recommendClient` and `indexName` to `instantsearch`

Replace `view` with the `layout` template or the `connectTrendingItems` connector

Replace component props with templates

Replace `translations` with `templates`

Replace `maxRecommendations` with `limit`

Remove `environment`

Replace `classNames` with `cssClasses`

Alternative for `trendingFacets`

Changes for `lookingSimilar`

Move recommendClient and indexName to instantsearch

Replace `view` with the `layout` template or the `connectLookingSimilar` connector

Replace component props with `templates`

Replace translations with `templates`

Replace `maxRecommendations` with `limit`

Remove `environment`

Replace `classNames` with `cssClasses`

`horizontalSlider`