trendingFacets

Shows a list of trending facet values.

If you’re using the deprecated recommend-js UI library, see trendingFacets.

Signature

trendingFacets({
  container: string | HTMLElement,
  facetName: string,
  // Optional parameters
  limit?: number,
  threshold?: number,
  fallbackParameters?: object,
  escapeHTML?: boolean,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

Package manager

import { trendingFacets } from 'instantsearch.js/es/widgets';

const { trendingFacets } = instantsearch.widgets;
// or directly use instantsearch.widgets.trendingFacets()

About this widget

Use the trendingFacets widget to display a list of trending facet values.

See also: Set up Algolia Recommend

Examples

JavaScript

trendingFacets({
  container: "#trendingFacets",
  facetName: "brand",
  templates: {
    item(item, { html }) {
      return html`<span>${item.facetValue}</span>`;
    },
  },
});

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

trendingFacets({
  // ...
  container: '#trendingFacets',
});

trendingFacets({
  container: document.querySelector("#trendingFacets"),
});

facetName · string · required

The facet attribute to get trending values for.

JavaScript

trendingFacets({
  // ...
  facetName: "brand",
});

limit · number

The number of trending facet values 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.

JavaScript

trendingFacets({
  // ...
  limit: 4,
});

threshold · number

The threshold for the recommendations confidence score (between 0 and 100). Only recommendations with a greater score are returned.

JavaScript

trendingFacets({
  // ...
  threshold: 80,
});

fallbackParameters · Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>

List of search parameters to send when there aren’t enough recommendations.

JavaScript

trendingFacets({
  // ...
  fallbackParameters: {
    filters: "category:Book",
  },
});

escapeHTML · boolean · default: true

Escapes HTML entities from recommendations string values.

JavaScript

trendingFacets({
  // ...
  escapeHTML: false,
});

templates · object

The templates to use for the widget.

JavaScript

trendingFacets({
  // ...
  templates: {
    // ...
  },
});

cssClasses · object · default: "{}"

The CSS classes you can override:

• 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 trending facet values.
• item. The list item.

JavaScript

trendingFacets({
  // ...
  cssClasses: {
    root: "MyCustomTrendingFacets",
    list: ["MyCustomTrendingFacets", "MyCustomTrendingFacets--subclass"],
  },
});

transformItems · 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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

trendingFacets({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      facetValue: item.facetValue.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. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

empty · string | function

The template to use when there are no trending facet values.

function

trendingFacets({
  // ...
  templates: {
    empty(_, { html }) {
      return html`<p>No trending facets.</p>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
trendingFacets({
  // ...
  templates: {
    empty: "No trending facets.",
  },
});

header · string | function

The template to use for the widget header. This template receives the items as well as the cssClasses object.

function

trendingFacets({
  // ...
  templates: {
    header({ cssClasses, items }, { html }) {
      return html`<h2 class=${cssClasses.title}>
        Trending (${items.length})
      </h2>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
trendingFacets({
  // ...
  templates: {
    header: "<h2>Trending ({{items.length}})</h2>",
  },
});

item · string | function

The template to use for each trending facet value. This template receives an object with facetName, facetValue, and _score.

function

trendingFacets({
  // ...
  templates: {
    item(item, { html }) {
      return html`<span>${item.facetValue}</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
trendingFacets({
  // ...
  templates: {
    item: `{{ facetValue }}`,
  },
});

HTML output

HTML

<section class="ais-TrendingFacets">
  <h3 class="ais-TrendingFacets-title">Trending</h3>
  <div class="ais-TrendingFacets-container">
    <ol class="ais-TrendingFacets-list">
      <li class="ais-TrendingFacets-item">...</li>
      <li class="ais-TrendingFacets-item">...</li>
      <li class="ais-TrendingFacets-item">...</li>
    </ol>
  </div>
</section>

Customize the UI with connectTrendingFacets

If you want to create your own UI of the trendingFacets widget, you can use connectors.

To use connectTrendingFacets, you can import it with the declaration relevant to how you installed InstantSearch.js.

Package manager

import { connectTrendingFacets } from 'instantsearch.js/es/connectors';

const { connectTrendingFacets } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectTrendingFacets()

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderTrendingFacets = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customTrendingFacets = connectTrendingFacets(renderTrendingFacets);

// 3. Instantiate
search.addWidgets([
  customTrendingFacets({
    // 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).

JavaScript

const renderTrendingFacets = (renderOptions, isFirstRender) => {
  const { items, widgetParams } = renderOptions;

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

  // Render the widget
};

Rendering options

items · object[]

The trending facet values from the Algolia Recommend API. Each item has facetName, facetValue, and _score properties.

JavaScript

const renderTrendingFacets = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

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

widgetParams · object

All original widget options forwarded to the render function.

JavaScript

const renderTrendingFacets = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

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

// ...

search.addWidgets([
  customTrendingFacets({
    // ...
    container: document.querySelector('#trendingFacets'),
  })
]);

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.

JavaScript

const customTrendingFacets = connectTrendingFacets(
  renderTrendingFacets
);

search.addWidgets([
  customTrendingFacets({
    // Required parameter
    facetName: string,
    // Optional parameters
    limit: number,
    threshold: number,
    fallbackParameters: object,
    escapeHTML: boolean,
    transformItems: function,
  })
]);

Instance options

facetName · string · required

The facet attribute to get trending values for.

JavaScript

customTrendingFacets({
  // ...
  facetName: "brand",
});

limit · number

The number of trending facet values 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.

JavaScript

customTrendingFacets({
  // ...
  limit: 4,
});

threshold · number

The threshold for the recommendations confidence score (between 0 and 100). Only recommendations with a greater score are returned.

JavaScript

customTrendingFacets({
  // ...
  threshold: 80,
});

fallbackParameters · Omit<SearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>

List of search parameters to send when there aren’t enough recommendations.

JavaScript

customTrendingFacets({
  // ...
  fallbackParameters: {
    filters: "category:Book",
  },
});

escapeHTML · boolean · default: true

Escapes HTML entities from recommendations string values.

JavaScript

customTrendingFacets({
  // ...
  escapeHTML: false,
});

transformItems · 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 and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

customTrendingFacets({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      facetValue: item.facetValue.toUpperCase(),
    }));
  },
});

Full example

HTML

<div id="trendingFacets"></div>

// Create the render function
const renderTrendingFacets = (renderOptions, isFirstRender) => {
  const { items, widgetParams } = renderOptions;

  widgetParams.container.innerHTML = `
    <ul>
      ${items
        .map(item => `<li>${item.facetValue}</li>`)
        .join('')}
    </ul>
  `;
};

// Create the custom widget
const customTrendingFacets = connectTrendingFacets(
  renderTrendingFacets
);

// Instantiate the custom widget
search.addWidgets([
  customTrendingFacets({
    container: document.querySelector('#trendingFacets'),
    facetName: 'brand',
  })
]);