> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TrendingFacets

> Shows a list of trending facet values.

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

<Note>
  If you're using the deprecated [`recommend-react`](https://algolia.com/old-docs/deprecated/recommend/api-reference/recommend-react) UI library,
  see [`<TrendingFacets>`](https://www.algolia.com/old-docs/deprecated/recommend/api-reference/recommend-js/trendingFacets/).
</Note>

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

## Import

```jsx JavaScript icon=code theme={"system"}
import { TrendingFacets } from "react-instantsearch";
```

## About this widget

Use the `<TrendingFacets>` widget to display a list of trending facet values.

See also: [Set up Algolia Recommend](/doc/guides/algolia-recommend/how-to/set-up)

<Tip>You can also create your own UI with [`useTrendingFacets`](#hook).</Tip>

## Examples

```jsx JavaScript icon=code theme={"system"}
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

<ParamField body="facetName" type="string" required>
  The facet attribute to get trending values for.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    facetName="brand"
  />;
  ```
</ParamField>

<ParamField body="itemComponent" type="(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.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    itemComponent={({ item }) => <span>{item.facetValue}</span>}
  />;
  ```
</ParamField>

<ParamField body="headerComponent" type="(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".

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    headerComponent={({ classNames, items }) => (
      <h2 className={classNames.title}>Trending ({items.length})</h2>
    )}
  />;
  ```
</ParamField>

<ParamField body="emptyComponent" type="() => JSX.Element">
  A component that renders when there are no trending facet values.

  When not provided, the widget displays a default empty state.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    emptyComponent={() => <p>No trending facets.</p>}
  />;
  ```
</ParamField>

<ParamField body="limit" type="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.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    limit={4}
  />;
  ```
</ParamField>

<ParamField body="threshold" type="number">
  The threshold for the recommendations confidence score (between 0 and 100).
  Only recommendations with a greater score are returned.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    threshold={80}
  />;
  ```
</ParamField>

<ParamField body="fallbackParameters" type="Omit<SearchParameters, hitsPerPage | length | offset | page>">
  List of [search parameters](/doc/api-reference/search-api-parameters) to send as additional filters when there aren't enough recommendations.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    fallbackParameters={{
      filters: "category:Book",
    }}
  />;
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Whether to escape HTML tags from recommendations string values.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    escapeHTML={false}
  />;
  ```
</ParamField>

<ParamField body="transformItems" type="(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](/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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        facetValue: item.facetValue.toUpperCase(),
      }));
    };

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

    ```tsx TypeScript theme={"system"}
    import type { TrendingFacetsProps } from "react-instantsearch";

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

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

<ParamField body="classNames" type="Partial<TrendingFacetsClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

  * `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.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    classNames={{
      root: "MyCustomTrendingFacets",
      list: "MyCustomTrendingFacets MyCustomTrendingFacets--subclass",
    }}
  />;
  ```
</ParamField>

<ParamField body="translations" type="Partial<TrendingFacetsTranslations>">
  A mapping of keys to translation values.

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

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    translations={{
      title: "Trending Brands",
    }}
  />;
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the widget's root element.

  ```jsx JavaScript icon=code theme={"system"}
  <TrendingFacets
    // ...
    className="MyCustomTrendingFacets"
  />;
  ```
</ParamField>

## 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](#parameters) and returns [APIs](#hook).
It must be used inside the [`<InstantSearch>`](/doc/api-reference/widgets/instantsearch/react) component.

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useTrendingFacets } from "react-instantsearch";

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

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

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomTrendingFacets {...props} />
```

### Parameters

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

<Note>
  When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
  Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
  Arrays and objects are automatically memoized.
</Note>

<ParamField body="facetName" type="string" required>
  The facet attribute to get trending values for.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useTrendingFacets({
    // ...
    facetName: "brand",
  });
  ```
</ParamField>

<ParamField body="limit" type="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.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useTrendingFacets({
    // ...
    limit: 4,
  });
  ```
</ParamField>

<ParamField body="threshold" type="number">
  The threshold for the recommendations confidence score (between 0 and 100).
  Only recommendations with a greater score are returned.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useTrendingFacets({
    // ...
    threshold: 80,
  });
  ```
</ParamField>

<ParamField body="fallbackParameters" type="Omit<SearchParameters, hitsPerPage | length | offset | page>">
  List of [search parameters](/doc/api-reference/search-api-parameters) to send as additional filters when there aren't enough recommendations.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useTrendingFacets({
    // ...
    fallbackParameters: {
      filters: "category:Book",
    },
  });
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Whether to escape HTML tags from recommendations string values.

  ```jsx JavaScript icon=code theme={"system"}
  const { items } = useTrendingFacets({
    // ...
    escapeHTML: false,
  });
  ```
</ParamField>

<ParamField body="transformItems" type="(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](/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`.

  <CodeGroup>
    ```jsx JavaScript theme={"system"}
    const transformItems = (items) => {
      return items.map((item) => ({
        ...item,
        facetValue: item.facetValue.toUpperCase(),
      }));
    };

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

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

    ```tsx TypeScript theme={"system"}
    import type { UseTrendingFacetsProps } from "react-instantsearch";

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

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

      return <>{/* Your JSX */}</>;
    }
    ```
  </CodeGroup>
</ParamField>

### APIs

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

<ResponseField name="items" type="TrendingFacetItem[]">
  The trending facet values returned from Algolia Recommend.
  Each item has `facetName`, `facetValue`, and `_score` properties.
</ResponseField>

### Example

<CodeGroup>
  ```jsx JavaScript theme={"system"}
  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>
    );
  }
  ```

  ```tsx TypeScript theme={"system"}
  import React from "react";
  import { useTrendingFacets, UseTrendingFacetsProps } from "react-instantsearch";

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

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