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

Getting started with the Recommend UI library

A

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-react
# or
npm install @algolia/recommend-react

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

Copy 
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

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('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
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#

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