> ## 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>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

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

```tsx Signature theme={"system"}
<FrequentlyBoughtTogether
  objectIDs={string[]}
  // Optional props
  itemComponent={function}
  headerComponent={function}
  emptyComponent={function}
  limit: {number},
  threshold: {number},
  queryParameters: {object},
  escapeHTML={boolean}
  transformItems={function}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { FrequentlyBoughtTogether } from "react-instantsearch";
```

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

<Tip>
  You can also create your own UI with [`useFrequentlyBoughtTogether`](#hook).
</Tip>

## Examples

```jsx JavaScript icon=code theme={"system"}
import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, FrequentlyBoughtTogether } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function Item({ item }) {
  return JSON.stringify(item);
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <FrequentlyBoughtTogether objectIDs={["5723537"]} itemComponent={Item} />
    </InstantSearch>
  );
}
```

### With carousel layout

Display the `<FrequentlyBoughtTogether>` widget as a [scrollable carousel](/doc/api-reference/widgets/frequently-bought-together/react#param-layout-component)

```jsx JavaScript icon=code theme={"system"}
import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import {
  InstantSearch,
  FrequentlyBoughtTogether,
  Carousel,
} from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function Item({ item }) {
  return JSON.stringify(item);
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <FrequentlyBoughtTogether
        objectIDs={["5723537"]}
        itemComponent={Item}
        layoutComponent={Carousel}
      />
    </InstantSearch>
  );
}
```

## Props

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

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    objectIDs={["5723537"]}
  />;
  ```
</ParamField>

<ParamField body="itemComponent" type="(props: { item: THit }) => JSX.Element">
  A component that renders each recommendation from the results.
  It receives an `item` prop.

  When not provided, the widget displays the recommendation as a JSON string.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    itemComponent={({ item }) => item.objectID}
  />;
  ```
</ParamField>

<ParamField body="headerComponent" type="(props: { classNames: string[], items: THit[], translations: object }) => JSX.Element">
  A component that renders a title header.
  It receives `classNames`, `items` and `translations` props.

  When not provided, the widget displays a default header.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    headerComponent={({ classNames, items }) => (
      <h2 className={classNames.title}>Recommendations ({items.length})</h2>
    )}
  />;
  ```
</ParamField>

<ParamField body="emptyComponent" type="() => JSX.Element">
  A component that renders when there are no recommendations.

  When not provided, the widget displays a default message.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    emptyComponent={() => <p>No recommendations.</p>}
  />;
  ```
</ParamField>

<ParamField body="layoutComponent" type="(props: RecommendLayoutProps) => JSX.Element" post={["since: v7.13.0"]}>
  The layout component to use to wrap all items.

  React InstantSearch provides a provides a built-in `<Carousel>` layout component with the following props:

  `classNames`:

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

  `translations`:

  * `nextButtonLabel`. The label for the next button.
  * `nextButtonTitle`. The title for the next button.
  * `previousButtonLabel`. The label for the previous button.
  * `previousButtonTitle`. The title for the previous button.
  * `listLabel`. The label for the list of recommendation.

  `previousIconComponent`. The component to render as the previous button.

  `nextIconComponent`. The component to render as the next button.

  <CodeGroup>
    ```jsx Carousel theme={"system"}
    import { Carousel } from "react-instantsearch";

    <FrequentlyBoughtTogether
      // ...
      layoutComponent={(props) => (
        <Carousel
          {...props}
          classNames={{ root: "MyRootClass" }}
          previousIconComponent={() => <p>Previous</p>}
          nextIconComponent={() => <p>Next</p>}
        />
      )}
    />;
    ```

    ```jsx Custom theme={"system"}
    <FrequentlyBoughtTogether
      // ...
      layoutComponent={(props) => (
        <ul>
          {props.items.map((item) => (
            <li key={item.objectID}>{item.objectID}</li>
          ))}
        </ul>
      )}
    />;
    ```
  </CodeGroup>
</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.

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

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    threshold={80}
  />;
  ```
</ParamField>

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

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    queryParameters={{
      filters: "category:Book",
    }}
  />;
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Whether to escape HTML tags from recommendations string values.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    escapeHTML={false}
  />;
  ```
</ParamField>

<ParamField body="transformItems" type="(items: THit[], metadata: { results: SearchResults }) => THit[]">
  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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.name.toUpperCase(),
      }));
    };

    function Search() {
      return (
        <FrequentlyBoughtTogether
          // ...
          transformItems={transformItems}
        />
      );
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type {
      FrequentlyBoughtTogetherProps
    } from 'react-instantsearch';

    const transformItems: FrequentlyBoughtTogetherProps[
      'transformItems'
    ] = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.name.toUpperCase(),
      }));
    };

    function Search() {
      return (
        <FrequentlyBoughtTogether
          // ...
          transformItems={transformItems}
        />
      );
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="classNames" type="Partial<FrequentlyBoughtTogetherClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

  * `root`. The widget's root element.
  * `emptyRoot`. The root 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.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    classNames={{
      root: "MyCustomFrequentlyBoughtTogether",
      list: "MyCustomFrequentlyBoughtTogether MyCustomFrequentlyBoughtTogether--subclass",
    }}
  />;
  ```
</ParamField>

<ParamField body="translations" type="Partial<RecommendTranslations>">
  A mapping of keys to translation values.

  * `title`. The title of the recommendation section.
  * `sliderLabel`. The label of the horizontal slider.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    translations={{
      title: "Frequently bought with…",
    }}
  />;
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the widget's root element.

  ```jsx JavaScript icon=code theme={"system"}
  <FrequentlyBoughtTogether
    // ...
    className="MyCustomFrequentlyBoughtTogether"
    title="My custom title"
  />;
  ```
</ParamField>

## Hook

React InstantSearch let you create your own UI for the `<FrequentlyBoughtTogether>` widget with `useFrequentlyBoughtTogether`.
Hooks provide APIs to access the widget state and interact with InstantSearch.

The `useFrequentlyBoughtTogether` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useFrequentlyBoughtTogether } from "react-instantsearch";

function CustomFrequentlyBoughtTogether(props) {
  const { items } = useFrequentlyBoughtTogether(props);

  return <>{/*Your JSX*/}</>;
}
```

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomFrequentlyBoughtTogether {...props} />
```

### Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

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

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useFrequentlyBoughtTogether({
    // ...
    objectIDs: ["5723537"],
  });
  ```
</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.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useFrequentlyBoughtTogether({
    // ...
    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.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useFrequentlyBoughtTogether({
    // ...
    threshold: 80,
  });
  ```
</ParamField>

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

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

<ParamField body="escapeHTML" type="boolean" default={true}>
  Whether to escape HTML tags from recommendations string values.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useFrequentlyBoughtTogether({
    // ...
    escapeHTML: false,
  });
  ```
</ParamField>

<ParamField body="transformItems" type="(items: THit[], metadata: { results: SearchResults }) => THit[]">
  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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.name.toUpperCase(),
      }));
    };

    function FrequentlyBoughtTogether() {
      const frequentlyBoughtTogetherApi = useFrequentlyBoughtTogether({
        // ...
        transformItems,
      });

      return <>{/* Your JSX */}</>;
    }
    ```

    ```tsx TypeScript theme={"system"}
    import type {
      UseFrequentlyBoughtTogetherProps
    } from 'react-instantsearch';

    const transformItems: UseFrequentlyBoughtTogetherProps[
      'transformItems'
    ] = (items) => {
      return items.map((item) => ({
        ...item,
        label: item.name.toUpperCase(),
      }));
    };

    function FrequentlyBoughtTogether() {
      const frequentlyBoughtTogetherApi = useFrequentlyBoughtTogether({
        // ...
        transformItems,
      });

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</ParamField>

### APIs

Hooks return APIs, such as state and functions.
You can use them to build your UI and interact with React InstantSearch.

<ResponseField name="items" type="THit[]">
  The matched recommendations returned from Algolia.
</ResponseField>

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  import React from "react";
  import { useFrequentlyBoughtTogether } from "react-instantsearch";

  function CustomFrequentlyBoughtTogether(props) {
    const { items } = useFrequentlyBoughtTogether(props);

    return (
      <ol>
        {items.map((item) => (
          <li key={item.objectID}>
            <div style={{ wordBreak: "break-all" }}>
              {JSON.stringify(item).slice(0, 100)}
            </div>
          </li>
        ))}
      </ol>
    );
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React from "react";
  import {
    useFrequentlyBoughtTogether,
    UseFrequentlyBoughtTogetherProps,
  } from "react-instantsearch";

  function CustomFrequentlyBoughtTogether(
    props: UseFrequentlyBoughtTogetherProps,
  ) {
    const { items } = useFrequentlyBoughtTogether(props);

    return (
      <ol>
        {items.map((item) => (
          <li key={item.objectID}>
            <div style={{ wordBreak: "break-all" }}>
              {JSON.stringify(item).slice(0, 100)}
            </div>
          </li>
        ))}
      </ol>
    );
  }
  ```
</CodeGroup>