TrendingItems - 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 <TrendingItems>.

Signature

<TrendingItems
  // Optional props
  facetName={string}
  facetValue={string}
  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 { TrendingItems } from "react-instantsearch";

Use the <TrendingItems> widget to display a list of trending items. See also: Set up Algolia Recommend

You can also create your own UI with useTrendingItems.

Examples

JavaScript

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

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

function Item({ item }) {
  return JSON.stringify(item);
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <TrendingItems
        facetName="category"
        facetValue="Book"
        itemComponent={Item}
      />
    </InstantSearch>
  );
}

With carousel layout

Display the <TrendingItems> widget as a scrollable carousel.

JavaScript

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

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

function Item({ item }) {
  return JSON.stringify(item);
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <TrendingItems
        facetName="category"
        facetValue="Book"
        itemComponent={Item}
        layoutComponent={Carousel}
      />
    </InstantSearch>
  );
}

Props

facetName

string

The facet attribute for which to get recommendations. This parameter should be used along with facetValue.

JavaScript

<TrendingItems
  // ...
  facetName="category"
  facetValue="Book"
/>;

facetValue

string

The value for the targeted facet name. This parameter should be used along with facetName.

JavaScript

<TrendingItems
  // ...
  facetName="category"
  facetValue="Book"
/>;

itemComponent

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

A component that renders each recommendation from the results. It receives an item prop.When not provided, the widget displays the recommendation as a JSON string.

JavaScript

<TrendingItems
  // ...
  itemComponent={({ item }) => item.objectID}
/>;

headerComponent

(props: { classNames: string[], items: THit[], 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.

JavaScript

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

emptyComponent

() => JSX.Element

A component that renders when there are no recommendations.When not provided, the widget displays a default message.

JavaScript

<TrendingItems
  // ...
  emptyComponent={() => <p>No recommendations.</p>}
/>;

layoutComponent

(props: RecommendLayoutProps) => JSX.Element

since: v7.13.0

The layout component to use to wrap all items.React InstantSearch provides a built-in <Carousel> layout component with the following props:classNames:

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.

translations:

nextButtonLabel. The label for the next button.
nextButtonTitle. The title for the next button.
previousButtonLabel. The label for the previous button.
previousButtonTitle. The title for the previous button.
listLabel. The label for the list of recommendation.

previousIconComponent. The component to render as the previous button.nextIconComponent. The component to render as the next button.

import { Carousel } from "react-instantsearch";

<TrendingItems
  // ...
  layoutComponent={(props) => (
    <Carousel
      {...props}
      classNames={{ root: "MyRootClass" }}
      previousIconComponent={() => <p>Previous</p>}
      nextIconComponent={() => <p>Next</p>}
    />
  )}
/>;

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 limit isn’t provided or set to 0, all matching recommendations are returned.

JavaScript

<TrendingItems
  // ...
  limit={4}
/>;

threshold

number

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

JavaScript

<TrendingItems
  // ...
  threshold={80}
/>;

queryParameters

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

List of search parameters to send.

JavaScript

<TrendingItems
  // ...
  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

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

escapeHTML

boolean

default:true

Whether to escape HTML tags from recommendations string values.

JavaScript

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

transformItems

(items: THit[], metadata: { results: SearchResults }) => THit[]

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,
    label: item.name.toUpperCase(),
  }));
};

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

classNames

Partial<TrendingItemsClassNames>

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 recommendations.
item. The list item.

JavaScript

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

translations

Partial<RecommendTranslations>

A mapping of keys to translation values.

title. The title of the recommendation section.
sliderLabel. The label of the horizontal slider.

JavaScript

<TrendingItems
  // ...
  translations={{
    title: "Trending Books",
  }}
/>;

...props

React.ComponentProps<'div'>

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

JavaScript

<TrendingItems
  // ...
  className="MyCustomTrendingItems"
  title="My custom title"
/>;

Hook

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

Usage

First, create your React component:

JavaScript

import { useTrendingItems } from "react-instantsearch";

function CustomTrendingItems(props) {
  const { items } = useTrendingItems(props);

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

Then, render the widget:

JavaScript

<CustomTrendingItems {...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

The facet attribute for which to get recommendations. This parameter should be used along with facetValue.

JavaScript

const { items } = useTrendingItems({
  // ...
  facetName: "category",
  facetValue: "Book",
});

facetValue

string

The value for the targeted facet name. This parameter should be used along with facetName.

JavaScript

const { items } = useTrendingItems({
  // ...
  facetName: "category",
  facetValue: "Book",
});

limit

number

JavaScript

const { items } = useTrendingItems({
  // ...
  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 } = useTrendingItems({
  // ...
  threshold: 80,
});

queryParameters

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

List of search parameters to send.

JavaScript

const { items } = useTrendingItems({
  // ...
  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 } = useTrendingItems({
  // ...
  fallbackParameters: {
    filters: "category:Book",
  },
});

escapeHTML

boolean

default:true

Whether to escape HTML tags from recommendations string values.

JavaScript

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

transformItems

(items: THit[], metadata: { results: SearchResults }) => THit[]

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

function TrendingItems() {
  const trendingItemsApi = useTrendingItems({
    // ...
    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

THit[]

The matched recommendations returned from Algolia.

Example

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

function CustomTrendingItems(props) {
  const { items } = useTrendingItems(props);

  return (
    <ol>
      {items.map((item) => (
        <li key={item.objectID}>
          <div style={{ wordBreak: "break-all" }}>
            {JSON.stringify(item).slice(0, 100)}
          </div>
        </li>
      ))}
    </ol>
  );
}

React InstantSearch

​Import

​About this widget

​Examples

​With carousel layout

​Props

​Hook

​Usage

​Parameters

​APIs

​Example

Import

About this widget

Examples

With carousel layout

Props

Hook

Usage

Parameters

APIs

Example