TrendingFacets - Algolia

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

If you’re using the deprecated recommend-react UI library, see <TrendingFacets>.

Signature

<TrendingFacets
  facetName={string}
  // Optional props
  itemComponent={function}
  headerComponent={function}
  emptyComponent={function}
  limit={number}
  threshold={number}
  queryParameters={object}
  fallbackParameters={object}
  escapeHTML={boolean}
  transformItems={function}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { TrendingFacets } from "react-instantsearch";

Use the <TrendingFacets> widget to display a list of trending facet values. See also: Set up Algolia Recommend

You can also create your own UI with useTrendingFacets.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, TrendingFacets } from "react-instantsearch";

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

function Item({ item }) {
  return <span>{item.facetValue}</span>;
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <TrendingFacets
        facetName="brand"
        itemComponent={Item}
      />
    </InstantSearch>
  );
}

Props

facetName

string

required

The facet attribute to get trending values for.

JavaScript

<TrendingFacets
  // ...
  facetName="brand"
/>;

itemComponent

(props: { item: TrendingFacetItem }) => JSX.Element

A component that renders each trending facet value. It receives an item prop with facetName, facetValue, and _score.When not provided, the widget displays the facetValue as plain text.

JavaScript

<TrendingFacets
  // ...
  itemComponent={({ item }) => <span>{item.facetValue}</span>}
/>;

headerComponent

(props: { classNames: object, items: TrendingFacetItem[], 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 with the title “Trending”.

JavaScript

<TrendingFacets
  // ...
  headerComponent={({ classNames, items }) => (
    <h2 className={classNames.title}>Trending ({items.length})</h2>
  )}
/>;

emptyComponent

() => JSX.Element

A component that renders when there are no trending facet values.When not provided, the widget displays a default empty state.

JavaScript

<TrendingFacets
  // ...
  emptyComponent={() => <p>No trending facets.</p>}
/>;

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}
/>;

queryParameters

Omit<SearchParameters, hitsPerPage | length | offset | page>

List of search parameters to send.

JavaScript

<TrendingFacets
  // ...
  queryParameters={{
    filters: "category:Book",
  }}
/>;

fallbackParameters

Omit<SearchParameters, hitsPerPage | length | offset | page>

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

JavaScript

<TrendingFacets
  // ...
  fallbackParameters={{
    filters: "category:Book",
  }}
/>;

escapeHTML

boolean

default:true

Whether to escape HTML tags from recommendations string values.

JavaScript

<TrendingFacets
  // ...
  escapeHTML={false}
/>;

transformItems

(items: TrendingFacetItem[], metadata: { results: RecommendResponse }) => TrendingFacetItem[]

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.

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

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

classNames

Partial<TrendingFacetsClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

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

JavaScript

<TrendingFacets
  // ...
  classNames={{
    root: "MyCustomTrendingFacets",
    list: "MyCustomTrendingFacets MyCustomTrendingFacets--subclass",
  }}
/>;

translations

Partial<TrendingFacetsTranslations>

A mapping of keys to translation values.

title. The title of the widget section. Defaults to "Trending".

JavaScript

<TrendingFacets
  // ...
  translations={{
    title: "Trending Brands",
  }}
/>;

...props

React.ComponentProps<'div'>

Any <div> prop to forward to the widget’s root element.

JavaScript

<TrendingFacets
  // ...
  className="MyCustomTrendingFacets"
/>;

Hook

React InstantSearch let you create your own UI for the <TrendingFacets> widget with useTrendingFacets. Hooks provide APIs to access the widget state and interact with InstantSearch. The useTrendingFacets Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useTrendingFacets } from "react-instantsearch";

function CustomTrendingFacets(props) {
  const { items } = useTrendingFacets(props);

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

Then, render the widget:

JavaScript

<CustomTrendingFacets {...props} />

Parameters

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

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

facetName

string

required

The facet attribute to get trending values for.

JavaScript

const { items } = useTrendingFacets({
  // ...
  facetName: "brand",
});

limit

number

JavaScript

const { items } = useTrendingFacets({
  // ...
  limit: 4,
});

threshold

number

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

JavaScript

const { items } = useTrendingFacets({
  // ...
  threshold: 80,
});

queryParameters

Omit<SearchParameters, hitsPerPage | length | offset | page>

List of search parameters to send.

JavaScript

const { items } = useTrendingFacets({
  // ...
  queryParameters: {
    filters: "category:Book",
  },
});

fallbackParameters

Omit<SearchParameters, hitsPerPage | length | offset | page>

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

JavaScript

const { items } = useTrendingFacets({
  // ...
  fallbackParameters: {
    filters: "category:Book",
  },
});

escapeHTML

boolean

default:true

Whether to escape HTML tags from recommendations string values.

JavaScript

const { items } = useTrendingFacets({
  // ...
  escapeHTML: false,
});

transformItems

(items: TrendingFacetItem[], metadata: { results: RecommendResponse }) => TrendingFacetItem[]

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

function TrendingFacets() {
  const trendingFacetsApi = useTrendingFacets({
    // ...
    transformItems,
  });

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

APIs

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

items

TrendingFacetItem[]

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

Example

import React from "react";
import { useTrendingFacets } from "react-instantsearch";

function CustomTrendingFacets(props) {
  const { items } = useTrendingFacets(props);

  return (
    <ol>
      {items.map((item, index) => (
        <li key={`${item.facetName}:${item.facetValue}:${index}`}>
          {item.facetValue}
        </li>
      ))}
    </ol>
  );
}

React InstantSearch

Documentation Index

​Import

​About this widget

​Examples

​Props

​Hook

​Usage

​Parameters

​APIs

​Example

Import

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example