UI Libraries / Recommend / Getting started with the Recommend UI library

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

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>

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

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 
1
2

<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 
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

/** @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 
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
42

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>
  );
}

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). If you specify multiple objectIDs you will get multiple sets of results, not a single set of aggregated results.

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

With a custom view

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

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

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

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

Going further

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,
    });
  },
});

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.
Previous
What is Recommend?
Next
Upgrade guide
Did you find this page helpful?