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 API reference for a comprehensive list of parameters and options.
Try out the Playground where you can fork a basic implementation and play around.

Keep reading to see how to install Recommend and build a basic implementation.

Installation# A

The Recommend library is available for JavaScript and for 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>

Algolia doesn’t provide support regarding third party services like jsDeliver or other CDNs. The code examples below will only work if you are using a package manager.

Displaying recommendations# A

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('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');
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('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');
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>
  );
}

You may have noticed a few options in the preceding example:

The initialized recommendClient lets the component fetch recommendations from the Algolia index specified in indexName.
The objectIDs parameter indicate for what records to retrieve recommendations from. It accepts an array so you can display recommendations for a single or for multiple records (for example, in a shopping cart).

Defining how to display items# A

The itemComponent parameter lets you display a custom layout and content for your recommended items. It can return a string or anything that’s a 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('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');
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('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');
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#

Going further# A

This is all you need for a basic implementation. To go further, 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>
  );
}

This outlines a basic Recommend implementation. 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# Found an issue? Edit this guide A Edit this guide

Displaying recommendations# Found an issue? Edit this guide A Edit this guide

Defining how to display items# Found an issue? Edit this guide A Edit this guide

With a custom view#

Going further# Found an issue? Edit this guide A Edit this guide

On this page

Installation# A

Displaying recommendations# A

Defining how to display items# A

Going further# A