UI libraries / InstantSearch.js / Widgets

Sep 05, 2024

frequentlyBoughtTogether

Signature

frequentlyBoughtTogether({
  container: string|HTMLElement,
  objectIDs: string[],
  // Optional parameters
  limit: number,
  threshold: number,
  queryParameters: object,
  escapeHTML: boolean,
  templates: object,
  cssClasses: object,
  transformItems: function,
});

Import

Copy

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

See code examples

About this widget

Use the frequentlyBoughtTogether widget to display a list of frequently bought together items.

Guides Set up Algolia Recommend

If you’re using the deprecated recommend-js UI library, please refer to the API reference for the frequentlyBoughtTogether function.

Examples

Copy
frequentlyBoughtTogether({
  container: '#frequentlyBoughtTogether',
  objectIDs: ['5723537'],
  templates: {
    item(recommendation, { html }) {
      return html`
        <h2>${recommendation.name}</h2>
        <p>${recommendation.description}</p>
      `;
    },
  },
});

With a carousel layout

Display the frequentlyBoughtTogether widget as a scrollable carousel.

Copy
import { carousel } from 'instantsearch.js/es/templates';
// or
const { carousel } = instantsearch.templates;

frequentlyBoughtTogether({
  container: '#frequentlyBoughtTogether',
  objectIDs: ['5723537'],
  templates: {
    item(recommendation, { html }) {
      return html`
        <h2>${recommendation.name}</h2>
        <p>${recommendation.description}</p>
      `;
    },
    layout: carousel(),
  },
});

Options


            container

type: string|HTMLElement

Required

The CSS Selector or HTMLElement to insert the widget into.

Copy

1
2
3
4
frequentlyBoughtTogether({
  // ...
  container: '#frequentlyBoughtTogether',
});


            objectIDs

type: string[]

Required

The list of objectIDs to get recommendations for. If you specify multiple objectIDs, you’ll get a single set of aggregated results from the requests, ordered by their score.

Each objectID you pass in the array counts towards the number of requests in your pricing plan. For example, if you want recommendations for the array ["A", "B", "C"], you’ll consume three requests from your quota, not one.

Copy

1
2
3
4
frequentlyBoughtTogether({
  // ...
  objectIDs: ['1', '2', '3'],
});


            limit

type: number

The number of recommendations to retrieve. Depending on the available recommendations and the other request parameters, the actual number of items may be lower than that. If limit isn’t provided or set to 0, all matching recommendations are returned.

Copy

1
2
3
4
frequentlyBoughtTogether({
  // ...
  limit: 4,
});


            threshold

type: number

The threshold for the recommendations confidence score (between 0 and 100). Only recommendations with a greater score are returned.

Copy

1
2
3
4
frequentlyBoughtTogether({
  // ...
  threshold: 80,
});


            queryParameters

type: Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>

List of search parameters to send.

Copy

1
2
3
4
5
6
frequentlyBoughtTogether({
  // ...
  queryParameters: {
    filters: 'category:Book',
  },
});


            escapeHTML

type: boolean

default: true

Optional

Escapes HTML entities from recommendations string values.

Copy

1
2
3
4
frequentlyBoughtTogether({
  // ...
  escapeHTML: false,
});


            templates

type: object

Optional

The templates to use for the widget.

Copy

1
2
3
4
5
6
frequentlyBoughtTogether({
  // ...
  templates: {
    // ...
  },
});


            cssClasses

type: object

default: {}

Optional

The CSS classes you can override:

root: the widget’s root element.
emptyRoot: the container element without results.
title: the widget’s title element.
container: the container of the list element.
list: the list of recommendations.
item: the list item.

Copy

1
2
3
4
5
6
7
8
9
10
frequentlyBoughtTogether({
  // ...
  cssClasses: {
    root: 'MyCustomFrequentlyBoughtTogether',
    list: [
      'MyCustomFrequentlyBoughtTogether',
      'MyCustomFrequentlyBoughtTogether--subclass',
    ],
  },
});


            transformItems

type: function

default: items => items

Optional

Receives the recommendations and is called before displaying them. It returns a new array with the same “shape” as the original. This is helpful when transforming or reordering items.

The entire results data is also available, including all regular response parameters.

Copy

1
2
3
4
5
6
7
8
9
frequentlyBoughtTogether({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      name: item.name.toUpperCase(),
    }));
  },
});

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.


            empty

type: string|function

Optional

The template to use when there are no recommendations.

Copy

1
2
3
4
5
6
7
8
frequentlyBoughtTogether({
  // ...
  templates: {
    empty(_, { html }) {
      return html`<p>No recommendations.</p>`;
    },
  },
});

1
2
3
4
5
6
7
// String-based templates are deprecated, use functions instead.
frequentlyBoughtTogether({
  // ...
  templates: {
    empty: 'No recommendations.',
  },
});


            header

type: string|function

Optional

The template to use for the recommendations header. This template receives the recommendations as well as the cssClasses object.

Copy

1
2
3
4
5
6
7
8
9
10
frequentlyBoughtTogether({
  // ...
  templates: {
    header({ cssClasses, items }, { html }) {
      return html`<h2 class=${cssClasses.title}>
        Recommendations (${items.length})
      </h2>`;
    },
  },
});

1
2
3
4
5
6
7
// String-based templates are deprecated, use functions instead.
frequentlyBoughtTogether({
  // ...
  templates: {
    header: '<h2>Recommendations ({{items.length}})</h2>',
  },
});


            item

type: string|function

Optional

The template to use for each recommendation. This template receives an object containing a single record.

Copy

1
2
3
4
5
6
7
8
9
10
11
frequentlyBoughtTogether({
  // ...
  templates: {
    item(recommendation, { html }) {
      return html`
        <h2>${recommendation.name}</h2>
        <p>${recommendation.description}</p>
      `;
    },
  },
});

1
2
3
4
5
6
7
8
9
10
// String-based templates are deprecated, use functions instead.
frequentlyBoughtTogether({
  // ...
  templates: {
    item: `
      <h2>{{ name }}</h2>
      <p>{{ description }}</p>
    `,
  },
});


            layout

since: v4.74.0

type: function

Optional

The template to use to wrap all items.

InstantSearch.js provides an out-of-the-box carousel layout template with the following options:

cssClasses

root: the carousel’s root element.
list: the list of recommendations.
item: the list item.
navigation: the navigation controls.
navigationPrevious: the “Previous” navigation control.
navigationNext: the “Next” navigation control.

templates

previous: the content of the “Previous” navigation control.
next: the content of the “Next” navigation control.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { carousel } from 'instantsearch.js/es/templates';
// or
const { carousel } = instantsearch.templates;

frequentlyBoughtTogether({
  // ...
  templates: {
    layout: carousel({
      cssClasses: {
        root: 'MyCustomCarousel',
      },
      templates: {
        previous({ html }) {
          return html`<p>Previous</p>`;
        },
        next({ html }) {
          return html`<p>Next</p>`;
        },
      },
    }),
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
frequentlyBoughtTogether({
  // ...
  templates: {
    layout({ items }, { html }) {
      return html`
        <ul>
          ${items.map((item) => html`<li><p>${item.objectID}</p></li>`)}
        </ul>
      `;
    },
  },
});

HTML output

Copy
<section class="ais-FrequentlyBoughtTogether">
  <h3 class="ais-FrequentlyBoughtTogether-title">Frequently Bought Together</h3>
  <div class="ais-FrequentlyBoughtTogether-container">
    <ol class="ais-FrequentlyBoughtTogether-list">
      <li class="ais-FrequentlyBoughtTogether-item">
        ...
      </li>
      <li class="ais-FrequentlyBoughtTogether-item">
        ...
      </li>
      <li class="ais-FrequentlyBoughtTogether-item">
        ...
      </li>
    </ol>
  </div>
</section>

Customize the UI with connectFrequentlyBoughtTogether

If you want to create your own UI of the frequentlyBoughtTogether widget, you can use connectors.

To use connectFrequentlyBoughtTogether, you can import it with the declaration relevant to how you installed InstantSearch.js.

Copy

1
import { connectFrequentlyBoughtTogether } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

// 1. Create a render function
const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customFrequentlyBoughtTogether = connectFrequentlyBoughtTogether(
  renderFrequentlyBoughtTogether
);

// 3. Instantiate
search.addWidgets([
  customFrequentlyBoughtTogether({
    // instance params
  })
]);

See code examples

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  const {
    object[] items,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Rendering options


            items

type: object[]

The matched recommendations from the Algolia API.

Copy
const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector('#frequentlyBoughtTogether').innerHTML = `
    <ul>
      ${items
        .map(item => `<li>${item.name}</li>`)
        .join('')}
    </ul>
  `;
};


            widgetParams

type: object

All original widget options forwarded to the render function.

Copy
const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customFrequentlyBoughtTogether({
    // ...
    container: document.querySelector('#frequentlyBoughtTogether'),
  })
]);

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customFrequentlyBoughtTogether = connectFrequentlyBoughtTogether(
  renderFrequentlyBoughtTogether
);

search.addWidgets([
  customFrequentlyBoughtTogether({
    objectIDs: string[],
    // Optional parameters
    limit: number,
    threshold: number,
    queryParameters: object,
    escapeHTML: boolean,
    transformItems: function,
  })
]);

Instance options


            objectIDs

type: string[]

Required

The list of objectIDs to get recommendations for. If you specify multiple objectIDs, you’ll get a single set of aggregated results from the requests, ordered by their score.

Copy

1
2
3
4
customFrequentlyBoughtTogether({
  // ...
  objectIDs: ['1', '2', '3'],
});


            limit

type: number

Copy

1
2
3
4
customFrequentlyBoughtTogether({
  // ...
  limit: 4,
});


            threshold

type: number

The threshold for the recommendations confidence score (between 0 and 100). Only recommendations with a greater score are returned.

Copy

1
2
3
4
customFrequentlyBoughtTogether({
  // ...
  threshold: 80,
});


            queryParameters

type: Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>

List of search parameters to send.

Copy

1
2
3
4
5
6
customFrequentlyBoughtTogether({
  // ...
  queryParameters: {
    filters: 'category:Book',
  },
});


            escapeHTML

type: boolean

default: true

Optional

Escapes HTML entities from recommendations string values.

Copy

1
2
3
4
customFrequentlyBoughtTogether({
  // ...
  escapeHTML: false,
});


            transformItems

type: function

default: items => items

Optional

Receives the recommendations and is called before displaying them. It returns a new array with the same “shape” as the original. This is helpful when transforming or reordering items.

The entire results data is also available, including all regular response parameters.

Copy

1
2
3
4
5
6
7
8
9
customFrequentlyBoughtTogether({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      name: item.name.toUpperCase(),
    }));
  },
});

Full example

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
// Create the render function
const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  const { items, widgetParams } = renderOptions;

  widgetParams.container.innerHTML = `
    <ul>
      ${items
        .map(item => `<li>${item.name}</li>`)
        .join('')}
    </ul>
  `;
};

// Create the custom widget
const customFrequentlyBoughtTogether = connectFrequentlyBoughtTogether(
  renderFrequentlyBoughtTogether
);

// Instantiate the custom widget
search.addWidgets([
  customFrequentlyBoughtTogether({
    container: document.querySelector('#frequentlyBoughtTogether'),
    objectIDs: ['5723537'],
  })
]);

Did you find this page helpful?

frequentlyBoughtTogether

About this widget

Examples

With a carousel layout

Options

Templates

HTML output

Customize the UI with connectFrequentlyBoughtTogether

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example

On this page