Getting started with the Recommend UI library

Get started with Recommend by building a recommendation UI.

This documentation offers a few ways to learn about the Recommend UI library:

Refer to the API reference for a comprehensive list of parameters and options.
In the Playground, you can fork a basic implementation and play around.

Installation

The Recommend library is available for JavaScript and React.

All Recommend packages are available on the npm registry.

Copy

1
2
3
yarn add @algolia/recommend-js
# or
npm install @algolia/recommend-js

If you don’t want to use a package manager, you can use a standalone endpoint:

Copy

1
2
3
4
5
6
<script src="https://cdn.jsdelivr.net/npm/@algolia/recommend-js"></script>
<script src="https://cdn.jsdelivr.net/npm/@algolia/recommend"></script>
<script>
  const { frequentlyBoughtTogether, relatedProducts, trendingItems, trendingFacets } = window['@algolia/recommend-js'];
  const recommend = window['@algolia/recommend'];
</script>

1
2
3
4
<script src="https://cdn.jsdelivr.net/npm/@algolia/recommend-react"></script>
<script>
  const { FrequentlyBoughtTogether, RelatedProducts, TrendingItems, TrendingFacets } = window['@algolia/recommend-react'];
</script>

1
2
3
4
<script src="https://cdn.jsdelivr.net/npm/@algolia/recommend-react"></script>
<script>
  const { FrequentlyBoughtTogether, Recommend, RelatedProducts, TrendingItems, TrendingFacets } = window['@algolia/recommend-react'];
</script>

Algolia doesn’t support third-party services like jsDelivr or other CDNs. The code examples below only work with a package manager.

Displaying recommendations

To get started, you need a container for your recommendations to go in—in this guide, one for Frequently Bought Together and one for Related Products. If you don’t have containers already, you can insert them into your markup:

Copy
<div id="frequentlyBoughtTogether"></div>
<div id="relatedProducts"></div>

Then, insert your recommendations by calling the frequentlyBoughtTogether function and providing the container. It can be a CSS selector or an Element.

The process is the same for relatedProducts.

Copy
/** @jsx h */
import { h } from 'preact';
import {
  frequentlyBoughtTogether,
  relatedProducts,
} from '@algolia/recommend-js';
import recommend from '@algolia/recommend';

const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
const indexName = 'YOUR_INDEX_NAME';
const currentObjectID = 'YOUR_OBJECT_ID';

frequentlyBoughtTogether({
  container: '#frequentlyBoughtTogether',
  recommendClient,
  indexName,
  objectIDs: [currentObjectID],
  itemComponent({ item }) {
    return (
      <pre>
        <code>{JSON.stringify(item)}</code>
      </pre>
    );
  },
});

relatedProducts({
  container: '#relatedProducts',
  recommendClient,
  indexName,
  objectIDs: [currentObjectID],
  itemComponent({ item }) {
    return (
      <pre>
        <code>{JSON.stringify(item)}</code>
      </pre>
    );
  },
});

Import the FrequentlyBoughtTogether and RelatedProducts and use them in your parent component.

Copy
import React from 'react';
import {
  FrequentlyBoughtTogether,
  RelatedProducts,
} from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
const indexName = 'YOUR_INDEX_NAME';

function App({ currentObjectID }) {
  // ...

  return (
    <div>
      <FrequentlyBoughtTogether
        recommendClient={recommendClient}
        indexName={indexName}
        objectIDs={[currentObjectID]}
        itemComponent={({ item }) => {
          return (
            <pre>
              <code>{JSON.stringify(item)}</code>
            </pre>
          );
        }}
      />
      <RelatedProducts
        recommendClient={recommendClient}
        indexName={indexName}
        objectIDs={[currentObjectID]}
        itemComponent={({ item }) => {
          return (
            <pre>
              <code>{JSON.stringify(item)}</code>
            </pre>
          );
        }}
      />
    </div>
  );
}

The preceding example uses these options:

The initialized recommendClient lets the component fetch recommendations from the Algolia index specified in indexName.
The objectIDs parameter indicates from which records to retrieve recommendations. It accepts an array to display recommendations for single or multiple records (for example, in a shopping cart). If you specify multiple objectIDs, you’ll get multiple sets of results, not a single set of aggregated results.

If you pass multiple objectIDs in an array, multiple Recommend requests will be deducted from your quota, one for each objectID you pass in the array. For example, if you want recommendations for the objectID array [ “A”,”B”,”C”], you’ll consume three requests from your quota, not one.

Defining how to display items

The itemComponent parameter lets you display a custom layout and content for your recommended items. It can return a string or any valid virtual DOM element. The following example creates a Preact component called RelatedItem to use as the template for each item.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/** @jsx h */
import { h } from 'preact';
import {
  frequentlyBoughtTogether,
  relatedProducts,
} from '@algolia/recommend-js';
import recommend from '@algolia/recommend';

const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
const indexName = 'YOUR_INDEX_NAME';
const currentObjectID = 'YOUR_OBJECT_ID';

function RelatedItem({ item }) {
  return (
    <a href={item.url}>
      <img src={item.image_link} alt={item.name} />
      <div>{item.category}</div>
      <div>{item.name}</div>
      <div>${item.price}</div>
    </a>
  );
}

relatedProducts({
  container: '#relatedProducts',
  recommendClient,
  indexName,
  objectIDs: [currentObjectID],
  itemComponent: RelatedItem,
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import React from 'react';
import {
  FrequentlyBoughtTogether,
  RelatedProducts,
} from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const recommendClient = recommend('YourApplicationID', 'YourSearchOnlyAPIKey');
const indexName = 'YOUR_INDEX_NAME';

function RelatedItem({ item }) {
  return (
    <a href={item.url}>
      <img src={item.image_link} alt={item.name} />
      <div>{item.category}</div>
      <div>{item.name}</div>
      <div>${item.price}</div>
    </a>
  );
}

function App({ currentObjectID }) {
  // ...

  return (
    <div>
      <FrequentlyBoughtTogether
        recommendClient={recommendClient}
        indexName={indexName}
        objectIDs={[currentObjectID]}
        itemComponent={RelatedItem}
      />
      <RelatedProducts
        recommendClient={recommendClient}
        indexName={indexName}
        objectIDs={[currentObjectID]}
        itemComponent={RelatedItem}
      />
    </div>
  );
}

With a custom view

The view prop lets you provide a custom container to render your items into. For example, you can use the Horizontal Slider view.

Any component you pass to the view prop can access props such as the itemComponent, recommendation items, and more.

The view prop lets you provide a custom container to render your items into. For example, you can use the Horizontal Slider view.

Any component you pass to the view prop can access props such as the itemComponent, recommendation items, and more.

Going further

To go further than this basic implementation, you can use headerComponent to customize the heading and fallbackComponent to display an alternative UI when no recommendations are returned. For example, you can display Related Products when no Frequently Bought Together items are available.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/** @jsx h */
import { h } from 'preact';
import {
  frequentlyBoughtTogether,
  relatedProducts,
} from '@algolia/recommend-js';
import recommend from '@algolia/recommend';

// ...

frequentlyBoughtTogether({
  container: '#frequentlyBoughtTogether',
  recommendClient,
  indexName,
  objectIDs: [currentObjectID],
  itemComponent: RelatedItem,
  fallbackComponent() {
    return relatedProducts({
      recommendClient,
      indexName,
      objectIDs: [currentObjectID],
      itemComponent: RelatedItem,
    });
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import React from 'react';
import {
  FrequentlyBoughtTogether,
  RelatedProducts,
} from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

// ...

function App({ currentObjectID }) {
  // ...

  return (
    <div>
      <FrequentlyBoughtTogether
        recommendClient={recommendClient}
        indexName={indexName}
        objectIDs={[currentObjectID]}
        itemComponent={RelatedItem}
        fallbackComponent={() => (
          <RelatedProducts
            recommendClient={recommendClient}
            indexName={indexName}
            objectIDs={[currentObjectID]}
            itemComponent={RelatedItem}
          />
        )}
      />
    </div>
  );
}

However, there’s a lot more you can do, like:

Define query parameters to create category-scoped carousels (for example, of the same brand or color).
Add recommendations in the shopping cart based on the already added items.

What is Recommend?

Upgrade guide

Did you find this page helpful?

Getting started with the Recommend UI library

Installation

Displaying recommendations

Defining how to display items

With a custom view

Going further

On this page