> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# trendingItems
> Shows a list of trending items.
export const Facet = () =>
facet
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
If you're using the deprecated [`recommend-js`](https://algolia.com/old-docs/deprecated/recommend/api-reference/recommend-js) UI library,
see [`trendingItems`](https://algolia.com/old-docs/deprecated/recommend/api-reference/recommend-js/trendingItems).
```ts Signature theme={"system"}
trendingItems({
container: string | HTMLElement,
// Optional parameters
facetName?: string,
facetValue?: string,
limit?: number,
threshold?: number,
queryParameters?: object,
fallbackParameters?: object,
escapeHTML?: boolean,
templates?: object,
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { trendingItems } from 'instantsearch.js/es/widgets';
```
```js CDN theme={"system"}
const { trendingItems } = instantsearch.widgets;
// or directly use instantsearch.widgets.trendingItems()
```
## About this widget
Use the `trendingItems` widget to display a list of trending items.
See also: [Set up Algolia Recommend](/doc/guides/algolia-recommend/how-to/set-up)
## Examples
```js JavaScript icon=code theme={"system"}
trendingItems({
container: "#trendingItems",
facetName: "category",
facetValue: "Book",
templates: {
item(recommendation, { html }) {
return html`
${recommendation.name}
${recommendation.description}
`;
},
},
});
```
### With a carousel layout
Display the `trendingItems` 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;
trendingItems({
container: "#trendingItems",
facetName: "category",
facetValue: "Book",
templates: {
item(recommendation, { html }) {
return html`
${recommendation.name}
${recommendation.description}
`;
},
layout: carousel(),
},
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
trendingItems({
// ...
container: '#trendingItems',
});
```
```js HTMLElement theme={"system"}
trendingItems({
container: document.querySelector("#trendingItems"),
});
```
The attribute to get recommendations for.
Use this parameter with [`facetValue`](/doc/api-reference/widgets/trending-items/js#param-facet-value).
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
facetName: "category",
facetValue: "Book",
});
```
The value for the targeted facet name.
This parameter should be used along with [`facetName`](/doc/api-reference/widgets/trending-items/js#param-facet-name).
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
facetName: "category",
facetValue: "Book",
});
```
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"}
trendingItems({
// ...
limit: 4,
});
```
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"}
trendingItems({
// ...
threshold: 80,
});
```
List of [search parameters](/doc/api-reference/search-api-parameters) to send.
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
queryParameters: {
filters: "category:Book",
},
});
```
List of [search parameters](/doc/api-reference/search-api-parameters) to send when there aren't enough recommendations.
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
fallbackParameters: {
filters: "category:Book",
},
});
```
Escapes HTML entities from recommendations string values.
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
escapeHTML: false,
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
trendingItems({
// ...
templates: {
// ...
},
});
```
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"}
trendingItems({
// ...
cssClasses: {
root: "MyCustomTrendingItems",
list: ["MyCustomTrendingItems", "MyCustomTrendingItems--subclass"],
},
});
```
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"}
trendingItems({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
name: item.name.toUpperCase(),
}));
},
});
```
## 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).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template to use when there are no recommendations.
```js function theme={"system"}
trendingItems({
// ...
templates: {
empty(_, { html }) {
return html`No recommendations.
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
trendingItems({
// ...
templates: {
empty: "No recommendations.",
},
});
```
The template to use for the recommendations header.
This template receives the recommendations as well as the `cssClasses` object.
```js function theme={"system"}
trendingItems({
// ...
templates: {
header({ cssClasses, items }, { html }) {
return html`
Recommendations (${items.length})
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
trendingItems({
// ...
templates: {
header: "Recommendations ({{items.length}})
",
},
});
```
The template to use for each recommendation.
This template receives an object containing a single record.
```js function theme={"system"}
trendingItems({
// ...
templates: {
item(recommendation, { html }) {
return html`
${recommendation.name}
${recommendation.description}
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
trendingItems({
// ...
templates: {
item: `
{{ name }}
{{ description }}
`,
},
});
```
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.
```js Carousel theme={"system"}
import { carousel } from 'instantsearch.js/es/templates';
// or
const { carousel } = instantsearch.templates;
trendingItems({
// ...
templates: {
layout: carousel({
cssClasses: {
root: 'MyCustomCarousel',
},
templates: {
previous({ html }) {
return html`Previous
`;
},
next({ html }) {
return html`Next
`;
},
},
}),
},
});
```
```js Custom theme={"system"}
trendingItems({
// ...
templates: {
layout({ items }, { html }) {
return html`
${items.map((item) => html`${item.objectID}
`;
},
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectTrendingItems`
If you want to create your own UI of the `trendingItems` widget, you can use connectors.
To use `connectTrendingItems`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectTrendingItems } from 'instantsearch.js/es/connectors';
```
```js CDN theme={"system"}
const { connectTrendingItems } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectTrendingItems()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderTrendingItems = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customTrendingItems = connectTrendingItems(renderTrendingItems);
// 3. Instantiate
search.addWidgets([
customTrendingItems({
// 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 renderTrendingItems = (renderOptions, isFirstRender) => {
const { items, widgetParams } = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Rendering options
The matched recommendations from the Algolia API.
```js JavaScript icon=code theme={"system"}
const renderTrendingItems = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector('#trendingItems').innerHTML = `
${items
.map(item => `- ${item.name}
`)
.join('')}
`;
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderTrendingItems = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = '...';
};
// ...
search.addWidgets([
customTrendingItems({
// ...
container: document.querySelector('#trendingItems'),
})
]);
```
### 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 customTrendingItems = connectTrendingItems(
renderTrendingItems
);
search.addWidgets([
customTrendingItems({
// Optional parameters
facetName: string,
facetValue: string,
limit: number,
threshold: number,
queryParameters: object,
fallbackParameters: object,
escapeHTML: boolean,
transformItems: function,
})
]);
```
#### Instance options
The facet attribute to get recommendations for.
This parameter should be used along with [`facetValue`](/doc/api-reference/widgets/trending-items/js#param-facet-value).
```js JavaScript icon=code theme={"system"}
customTrendingItems({
// ...
facetName: "category",
facetValue: "Book",
});
```
The value for the targeted facet name.
This parameter should be used along with [`facetName`](/doc/api-reference/widgets/trending-items/js#param-facet-name).
```js JavaScript icon=code theme={"system"}
customTrendingItems({
// ...
facetName: "category",
facetValue: "Book",
});
```
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"}
customTrendingItems({
// ...
limit: 4,
});
```
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"}
customTrendingItems({
// ...
threshold: 80,
});
```
List of [search parameters](/doc/api-reference/search-api-parameters) to send.
```js JavaScript icon=code theme={"system"}
customTrendingItems({
// ...
queryParameters: {
filters: "category:Book",
},
});
```
List of [search parameters](/doc/api-reference/search-api-parameters) to send when there aren't enough recommendations.
```js JavaScript icon=code theme={"system"}
customTrendingItems({
// ...
fallbackParameters: {
filters: "category:Book",
},
});
```
Escapes HTML entities from recommendations string values.
```js JavaScript icon=code theme={"system"}
customTrendingItems({
// ...
escapeHTML: false,
});
```
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"}
customTrendingItems({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
name: item.name.toUpperCase(),
}));
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderTrendingItems = (renderOptions, isFirstRender) => {
const { items, widgetParams } = renderOptions;
widgetParams.container.innerHTML = `
${items
.map(item => `- ${item.name}
`)
.join('')}
`;
};
// Create the custom widget
const customTrendingItems = connectTrendingItems(
renderTrendingItems
);
// Instantiate the custom widget
search.addWidgets([
customTrendingItems({
container: document.querySelector('#trendingItems'),
})
]);
```