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

# ais-frequently-bought-together

> Shows recommendations from the "Frequently bought together" model.

```vue Signature theme={"system"}
<ais-frequently-bought-together
  :objectIDs="string[]"
  // Optional parameters
  :limit="number"
  :threshold="number"
  :query-parameters="object"
  :fallback-parameters="object"
  :escapeHTML="boolean"
  :transform-items="function"
  layout="list | carousel"
  :class-names="object"
/>
```

## Import

**Component**

To ensure optimal bundle sizes,
see [Optimize build size](https://www.algolia.com/doc/guides/building-search-ui/going-further/improve-performance/vue.md#optimize-build-size).

```js Vue icon=code theme={"system"}
import { AisFrequentlyBoughtTogether } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisFrequentlyBoughtTogether,
  },
  // ...
};
```

**Plugin**

This imports all widgets, even the ones you don't use.
For more information, see [Get started with Vue InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/getting-started/vue.md).

```js JavaScript icon="code" theme={"system"} theme={"system"} theme={"system"} theme={"system"}
import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);
```

## About this widget

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

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

## Examples

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']">
  <template v-slot:item="{ item }">
    {{ item.name }}
  </template>
</ais-frequently-bought-together>
```

### With carousel layout

To display the recommendations as a scrollable carousel, set the [`layout`](#param-layout) prop to `carousel`.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']" layout="carousel">
  <template v-slot:item="{ item }">
    {{ item.name }}
  </template>
</ais-frequently-bought-together>
```

## Props

**objectIDs** `string[]` *required*

The list of object IDs to get recommendations for.
If you specify several object IDs,
you'll get a single set of aggregated results from the requests, ordered by their score.

> [!WARNING]
>
> Each `objectID` counts as one Recommend request,
> even when you pass multiple IDs in one array.
> For example, `["A", "B", "C"]` counts as three requests and
> can affect your [quota](https://www.algolia.com/pricing).

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']" />
```

**limit** `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 you omit `limit` or set it to 0, the widget returns all matching recommendations.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :limit="4"
/>
```

**threshold** `number`

The threshold for the recommendations confidence score (between 0 and 100).
The widget only returns recommendations with a greater score.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :threshold="80"
/>
```

**query-parameters** `Omit\<SearchParameters, hitsPerPage | length | offset | page\>`

[Search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters.md) to apply to the recommendation request.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :query-parameters="{ filters: 'category:Book' }"
/>
```

**fallback-parameters** `Omit\<SearchParameters, hitsPerPage | length | offset | page\>`

List of [search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters.md)
to send as an extra filter (A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints.) set when there aren't enough recommendations.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :fallback-parameters="{ filters: 'category:Book' }"
/>
```

**escapeHTML** `boolean` (default: true)

Whether to escape HTML tags from recommendations string values.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :escapeHTML="false"
/>
```

**transform-items** `function` (default: items => items)

A function to transform or reorder recommendations before the widget displays them.
It returns an array of items with the same structure.

> [!NOTE]
>
> To [prevent creating infinite loops](https://support.algolia.com/hc/en-us/articles/4406511683217-Vue-InstantSearch-How-do-I-prevent-infinite-loops),
> avoid passing arrays, objects, or functions directly in the template.
> These values aren't referentially equal on each render,
> which causes the widget to re-register every time.
> Instead, define them in your component's `data` option and reference them in the template.

```vue Vue icon=code theme={"system"}
<template>
  <!-- ... -->
  <ais-frequently-bought-together
    :objectIDs="['5723537']"
    :transform-items="transformItems"
  />
</template>

<script>
  export default {
    methods: {
      transformItems(items) {
        return items.map(item => ({
          ...item,
          name: item.name.toUpperCase(),
        }));
      },
    },
  };
</script>
```

**layout** `'list' | 'carousel'` (default: 'list')

How to display the recommendations:

* `list`. A list of items.
* `carousel`. A horizontally scrollable carousel with "Previous" and "Next" navigation buttons.

The [`item`](#param-item) slot applies to both layouts.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  layout="carousel"
/>
```

**class-names** `object` (default: \{})

The [CSS classes you can override](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/vue.md#style-your-widgets):

* `ais-FrequentlyBoughtTogether`. The widget's root element.
* `ais-FrequentlyBoughtTogether--empty`. The root element without results.
* `ais-FrequentlyBoughtTogether-title`. The widget's title element.
* `ais-FrequentlyBoughtTogether-container`. The container of the list element.
* `ais-FrequentlyBoughtTogether-list`. The list of recommendations.
* `ais-FrequentlyBoughtTogether-item`. The list item.

With the `carousel` layout, the `ais-FrequentlyBoughtTogether-list` and `ais-FrequentlyBoughtTogether-item` classes apply to the carousel's list and items.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together
  // ...
  :class-names="{
    'ais-FrequentlyBoughtTogether': 'MyCustomFrequentlyBoughtTogether',
    'ais-FrequentlyBoughtTogether-list': 'MyCustomFrequentlyBoughtTogetherList',
    // ...
  }"
/>
```

## Customize the UI

**default**

The slot to override the complete DOM output of the widget.
The widget only uses this slot if you don't provide any other slot.

**Scope**

* `items: object[]`. The recommendations.
* `sendEvent: (eventType, hit, eventName) => void`. The function to send `click` or `conversion` events.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']">
  <template v-slot="{ items, sendEvent }">
    <ul>
      <li v-for="item in items" :key="item.objectID">
        <a
          :href="item.url"
          @click="sendEvent('click', item, 'Product Clicked')"
        >
          {{ item.name }}
        </a>
      </li>
    </ul>
  </template>
</ais-frequently-bought-together>
```

**item**

The slot to override the DOM output of each recommendation.
If you don't provide it, the widget displays the recommendation as a JSON string.

**Scope**

* `item: object`. A single recommendation with all its attributes.
* `sendEvent: (eventType, hit, eventName) => void`. The function to send `click` or `conversion` events.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']">
  <template v-slot:item="{ item, sendEvent }">
    <a :href="item.url" @click="sendEvent('click', item, 'Product Clicked')">
      {{ item.name }}
    </a>
  </template>
</ais-frequently-bought-together>
```

**header**

The slot to override the DOM output of the title header.
The widget doesn't render the header when there are no recommendations.
If you don't provide it, the widget displays "Frequently bought together" as the title.

**Scope**

* `items: object[]`. The recommendations.
* `translations: object`. The widget's translations, such as `title`.
* `classNames: object`. The widget's CSS classes, such as `title`.

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']">
  <template v-slot:header="{ items, classNames }">
    <h2 :class="classNames.title">Recommendations ({{ items.length }})</h2>
  </template>
</ais-frequently-bought-together>
```

**empty**

The slot to override the DOM output when there are no recommendations.
If you don't provide it, the widget displays "No results".

```vue Vue icon=code theme={"system"}
<ais-frequently-bought-together :objectIDs="['5723537']">
  <template v-slot:empty>
    <p>No recommendations.</p>
  </template>
</ais-frequently-bought-together>
```

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