> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# frequentlyBoughtTogether

> Shows recommendations from the "Frequently Bought Together" model.

<Note>
  If you're using the deprecated [`recommend-js`](https://algolia.com/old-docs/deprecated/recommend/api-reference/recommend-js) UI library,
  see [`frequentlyBoughtTogether`](https://algolia.com/old-docs/deprecated/recommend/api-reference/recommend-js/frequentlyBoughtTogether).
</Note>

```ts Signature theme={"system"}
frequentlyBoughtTogether({
  container: string | HTMLElement,
  objectIDs: string[],
  // Optional parameters
  limit?: number,
  threshold?: number,
  queryParameters?: object,
  escapeHTML?: boolean,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';
  ```

  ```js CDN theme={"system"}
  const { frequentlyBoughtTogether } = instantsearch.widgets;
  // or directly use instantsearch.widgets.frequentlyBoughtTogether()
  ```
</CodeGroup>

## About this widget

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

See also: [Set up Algolia Recommend](/doc/guides/algolia-recommend/how-to/set-up)

## Examples

```js JavaScript icon=code theme={"system"}
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](#param-layout).

```js JavaScript icon=code theme={"system"}
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

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    frequentlyBoughtTogether({
      // ...
      container: '#frequentlyBoughtTogether',
    });
    ```

    ```js HTMLElement theme={"system"}
    frequentlyBoughtTogether({
      container: document.querySelector("#frequentlyBoughtTogether"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="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.

  <Warning>
    Each `objectID` you pass in the array counts towards the number of requests in
    your [pricing plan](https://www.algolia.com/pricing). For example, if you
    want recommendations for the array `["A", "B", "C"]`, you'll consume three
    requests from your quota, not one.
  </Warning>

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    objectIDs: ["1", "2", "3"],
  });
  ```
</ParamField>

<ParamField body="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.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    limit: 4,
  });
  ```
</ParamField>

<ParamField body="threshold" type="number">
  The threshold for the recommendations confidence score (between 0 and 100).
  Only recommendations with a greater score are returned.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    threshold: 80,
  });
  ```
</ParamField>

<ParamField body="queryParameters" type="Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>">
  List of [search parameters](/doc/api-reference/search-api-parameters) to send.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    queryParameters: {
      filters: "category:Book",
    },
  });
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Escapes HTML entities from recommendations string values.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    escapeHTML: false,
  });
  ```
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):

  * `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.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    cssClasses: {
      root: "MyCustomFrequentlyBoughtTogether",
      list: [
        "MyCustomFrequentlyBoughtTogether",
        "MyCustomFrequentlyBoughtTogether--subclass",
      ],
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  A function that receives the list of items before they are displayed.
  It should return a new array with the same structure.
  Use this to transform, filter, or reorder the items.

  The function also has access to the full `results` data,
  including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  frequentlyBoughtTogether({
    // ...
    transformItems(items) {
      return items.map((item) => ({
        ...item,
        name: item.name.toUpperCase(),
      }));
    },
  });
  ```
</ParamField>

## Templates

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

Each template includes an `html` function,
which you can use as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="empty" type="string | function">
  The template to use when there are no recommendations.

  <CodeGroup>
    ```js function theme={"system"}
    frequentlyBoughtTogether({
      // ...
      templates: {
        empty(_, { html }) {
          return html`<p>No recommendations.</p>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    frequentlyBoughtTogether({
      // ...
      templates: {
        empty: "No recommendations.",
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="header" type="string | function">
  The template to use for the recommendations header.
  This template receives the recommendations as well as the `cssClasses` object.

  <CodeGroup>
    ```js function theme={"system"}
    frequentlyBoughtTogether({
      // ...
      templates: {
        header({ cssClasses, items }, { html }) {
          return html`<h2 class=${cssClasses.title}>
            Recommendations (${items.length})
          </h2>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    frequentlyBoughtTogether({
      // ...
      templates: {
        header: "<h2>Recommendations ({{items.length}})</h2>",
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="item" type="string | function">
  The template to use for each recommendation.
  This template receives an object containing a single record.

  <CodeGroup>
    ```js function theme={"system"}
    frequentlyBoughtTogether({
      // ...
      templates: {
        item(recommendation, { html }) {
          return html`
            <h2>${recommendation.name}</h2>
            <p>${recommendation.description}</p>
          `;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    frequentlyBoughtTogether({
      // ...
      templates: {
        item: `
          <h2>{{ name }}</h2>
          <p>{{ description }}</p>
        `,
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="layout" type="function" post={['since: v4.74.0']}>
  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.

  <CodeGroup>
    ```js Carousel theme={"system"}
    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>`;
            },
          },
        }),
      },
    });
    ```

    ```js Custom theme={"system"}
    frequentlyBoughtTogether({
      // ...
      templates: {
        layout({ items }, { html }) {
          return html`
            <ul>
              ${items.map((item) => html`<li><p>${item.objectID}</p></li>`)}
            </ul>
          `;
        },
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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.

<CodeGroup>
  ```js Package manager theme={"system"}
  import { connectFrequentlyBoughtTogether } from 'instantsearch.js/es/connectors';
  ```

  ```js CDN theme={"system"}
  const { connectFrequentlyBoughtTogether } = instantsearch.connectors;
  // or directly use instantsearch.connectors.connectFrequentlyBoughtTogether()
  ```
</CodeGroup>

Then it's a 3-step process:

```js JavaScript icon=code theme={"system"}
// 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
  }),
]);
```

### 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).

```js JavaScript icon=code theme={"system"}
const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
  const { items, widgetParams } = renderOptions;

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

  // Render the widget
};
```

#### Rendering options

<ParamField body="items" type="object[]">
  The matched recommendations from the Algolia API.

  ```js JavaScript icon=code theme={"system"}
  const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
    const { items } = renderOptions;

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

<ParamField body="widgetParams" type="object">
  All original widget options forwarded to the render function.

  ```js JavaScript icon=code theme={"system"}
  const renderFrequentlyBoughtTogether = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

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

  // ...

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

### Create and instantiate the custom widget

First, create your custom widgets using a rendering function.
Then, instantiate them with parameters.

There are two kinds of parameters you can pass:

* **Instance parameters**. Predefined options that configure Algolia's behavior.
* **Custom parameters**. Parameters you define to make the widget reusable and adaptable.

Inside the `renderFunction`, both instance and custom parameters are accessible through `connector.widgetParams`.

```js JavaScript icon=code theme={"system"}
const customFrequentlyBoughtTogether = connectFrequentlyBoughtTogether(
  renderFrequentlyBoughtTogether
);

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

#### Instance options

<ParamField body="objectIDs" type="string[]" required>
  The list of object IDs for which to get recommendations.
  If you specify multiple object IDs,
  you'll get a single set of aggregated results from the requests, ordered by their score.

  <Warning>
    Each `objectID` you pass in the array counts towards the number of requests in
    your [pricing plan](https://www.algolia.com/pricing). For example, if you
    want recommendations for the array `["A", "B", "C"]`, you'll consume three
    requests from your quota, not one.
  </Warning>

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    objectIDs: ["1", "2", "3"],
  });
  ```
</ParamField>

<ParamField body="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.

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    limit: 4,
  });
  ```
</ParamField>

<ParamField body="threshold" type="number">
  The threshold for the recommendations confidence score (between 0 and 100).
  Only recommendations with a greater score are returned.

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    threshold: 80,
  });
  ```
</ParamField>

<ParamField body="queryParameters" type="Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>">
  List of [search parameters](/doc/api-reference/search-api-parameters) to send.

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    queryParameters: {
      filters: "category:Book",
    },
  });
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Escapes HTML entities from recommendations string values.

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    escapeHTML: false,
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  A function that receives the list of items before they are displayed.
  It should return a new array with the same structure.
  Use this to transform, filter, or reorder the items.

  The function also has access to the full `results` data,
  including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  customFrequentlyBoughtTogether({
    // ...
    transformItems(items) {
      return items.map((item) => ({
        ...item,
        name: item.name.toUpperCase(),
      }));
    },
  });
  ```
</ParamField>

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="frequentlyBoughtTogether"></div>
  ```

  ```js JavaScript theme={"system"}
  // 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'],
    })
  ]);
  ```
</CodeGroup>