> ## 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-trending-items

> Shows a list of trending items.

```vue Signature theme={"system"}
<ais-trending-items
  // Optional parameters
  facet-name="string"
  facet-value="string"
  :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 { AisTrendingItems } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

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

**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 `ais-trending-items` to display items that are gaining popularity based on conversion events.
By default, it retrieves [trending items](https://www.algolia.com/doc/guides/algolia-recommend/overview#trending-items-and-trending-facets-value) across the index.
To retrieve trending items within a specific category or other facet value,
set `facet-name` and `facet-value`.

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-trending-items facet-name="category" facet-value="Book">
  <template v-slot:item="{ item }">
    {{ item.name }}
  </template>
</ais-trending-items>
```

### 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-trending-items layout="carousel">
  <template v-slot:item="{ item }">
    {{ item.name }}
  </template>
</ais-trending-items>
```

## Props

**facet-name** `string`

The facet (An attribute in your records that lets users filter or group results (for example, by color, brand, or price).) attribute to get recommendations for.
Use this prop with [`facet-value`](#param-facet-value).

```vue Vue icon=code theme={"system"}
<ais-trending-items
  // ...
  facet-name="category"
  facet-value="Book"
/>
```

**facet-value** `string`

The value for the targeted facet name.
Use this prop with [`facet-name`](#param-facet-name).

```vue Vue icon=code theme={"system"}
<ais-trending-items
  // ...
  facet-name="category"
  facet-value="Book"
/>
```

**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-trending-items
  // ...
  :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-trending-items
  // ...
  :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-trending-items
  // ...
  :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-trending-items
  // ...
  :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-trending-items
  // ...
  :escapeHTML="false"
/>
```

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

A function that receives the items before the widget displays them.
It returns a new array with the same "shape" as the original.
This is helpful when transforming or reordering items.

> [!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-trending-items :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-trending-items
  // ...
  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-TrendingItems`. The widget's root element.
* `ais-TrendingItems--empty`. The root element without results.
* `ais-TrendingItems-title`. The widget's title element.
* `ais-TrendingItems-container`. The container of the list element.
* `ais-TrendingItems-list`. The list of recommendations.
* `ais-TrendingItems-item`. The list item.

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

```vue Vue icon=code theme={"system"}
<ais-trending-items
  // ...
  :class-names="{
    'ais-TrendingItems': 'MyCustomTrendingItems',
    'ais-TrendingItems-list': 'MyCustomTrendingItemsList',
    // ...
  }"
/>
```

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

**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-trending-items>
  <template v-slot:item="{ item, sendEvent }">
    <a :href="item.url" @click="sendEvent('click', item, 'Product Clicked')">
      {{ item.name }}
    </a>
  </template>
</ais-trending-items>
```

**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 "Trending items" 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-trending-items>
  <template v-slot:header="{ items, classNames }">
    <h2 :class="classNames.title">Trending ({{ items.length }})</h2>
  </template>
</ais-trending-items>
```

**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-trending-items>
  <template v-slot:empty>
    <p>No trending items.</p>
  </template>
</ais-trending-items>
```

## HTML output

```html HTML icon=code-xml theme={"system"}
<section class="ais-TrendingItems">
  <h3 class="ais-TrendingItems-title">Trending items</h3>
  <div class="ais-TrendingItems-container">
    <ol class="ais-TrendingItems-list">
      <li class="ais-TrendingItems-item">...</li>
      <li class="ais-TrendingItems-item">...</li>
      <li class="ais-TrendingItems-item">...</li>
    </ol>
  </div>
</section>
```