From b55881a15a06bed4dbd9bf37c2f1f9584e77042a Mon Sep 17 00:00:00 2001
From: Raed <raed.chammam@algolia.com>
Date: Mon, 10 Feb 2025 08:15:54 +0100
Subject: [PATCH 1/4] feat(recommend): add Trending-Facets model

---
 examples/js/getting-started/src/app.js        |  13 +-
 examples/react/getting-started/src/App.tsx    |  20 +-
 .../src/components/Carousel.tsx               |  55 ++--
 .../src/components/TrendingFacets.tsx         | 167 +++++++++++
 .../src/components/index.ts                   |   1 +
 .../instantsearch.js/src/connectors/index.ts  |   2 +
 .../trending-facets/connectTrendingFacets.ts  | 175 +++++++++++
 .../src/connectors/trending-facets/types.ts   |   6 +
 .../instantsearch.js/src/widgets/index.ts     |   1 +
 .../trending-facets/trending-facets.tsx       | 273 ++++++++++++++++++
 .../src/connectors/useTrendingFacets.ts       |  26 ++
 .../react-instantsearch-core/src/index.ts     |   1 +
 .../src/widgets/TrendingFacets.tsx            |  92 ++++++
 .../react-instantsearch/src/widgets/index.ts  |   1 +
 14 files changed, 790 insertions(+), 43 deletions(-)
 create mode 100644 packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
 create mode 100644 packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
 create mode 100644 packages/instantsearch.js/src/connectors/trending-facets/types.ts
 create mode 100644 packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
 create mode 100644 packages/react-instantsearch-core/src/connectors/useTrendingFacets.ts
 create mode 100644 packages/react-instantsearch/src/widgets/TrendingFacets.tsx

diff --git a/examples/js/getting-started/src/app.js b/examples/js/getting-started/src/app.js
index 88bfc54a49..1aff8d1171 100644
--- a/examples/js/getting-started/src/app.js
+++ b/examples/js/getting-started/src/app.js
@@ -8,7 +8,7 @@ import {
   panel,
   refinementList,
   searchBox,
-  trendingItems,
+  trendingFacets,
 } from 'instantsearch.js/es/widgets';
 
 import 'instantsearch.css/themes/satellite.css';
@@ -56,19 +56,14 @@ search.addWidgets([
   pagination({
     container: '#pagination',
   }),
-  trendingItems({
+  trendingFacets({
     container: '#trending',
     limit: 6,
+    facetName: 'brand',
     templates: {
       item: (item, { html }) => html`
         <div>
-          <article>
-            <div>
-              <img src="${item.image}" />
-              <h2>${item.name}</h2>
-            </div>
-            <a href="/products.html?pid=${item.objectID}">See product</a>
-          </article>
+          <h2>${item.facetName}: ${item.facetValue}</h2>
         </div>
       `,
       layout: carousel(),
diff --git a/examples/react/getting-started/src/App.tsx b/examples/react/getting-started/src/App.tsx
index 857391877e..870229ae6f 100644
--- a/examples/react/getting-started/src/App.tsx
+++ b/examples/react/getting-started/src/App.tsx
@@ -9,7 +9,7 @@ import {
   Pagination,
   RefinementList,
   SearchBox,
-  TrendingItems,
+  TrendingFacets,
   Carousel,
 } from 'react-instantsearch';
 
@@ -61,8 +61,8 @@ export function App() {
                 <Pagination />
               </div>
               <div>
-                <TrendingItems
-                  itemComponent={ItemComponent}
+                <TrendingFacets
+                  facetName="brand"
                   limit={6}
                   layoutComponent={Carousel}
                 />
@@ -96,17 +96,3 @@ function HitComponent({ hit }: { hit: HitType }) {
     </article>
   );
 }
-
-function ItemComponent({ item }: { item: Hit }) {
-  return (
-    <div>
-      <article>
-        <div>
-          <img src={item.image} />
-          <h2>{item.name}</h2>
-        </div>
-        <a href={`/products.html?pid=${item.objectID}`}>See product</a>
-      </article>
-    </div>
-  );
-}
diff --git a/packages/instantsearch-ui-components/src/components/Carousel.tsx b/packages/instantsearch-ui-components/src/components/Carousel.tsx
index 7916447a37..46d77752b7 100644
--- a/packages/instantsearch-ui-components/src/components/Carousel.tsx
+++ b/packages/instantsearch-ui-components/src/components/Carousel.tsx
@@ -2,6 +2,7 @@
 import { cx } from '../lib';
 
 import { createDefaultItemComponent } from './recommend-shared';
+import { isTrendingFacetHit } from './TrendingFacets';
 
 import type {
   ComponentProps,
@@ -11,6 +12,7 @@ import type {
   Renderer,
   SendEventForHits,
 } from '../types';
+import type { TrendingFacetHit } from './TrendingFacets';
 
 export type CarouselProps<
   TObject,
@@ -20,7 +22,7 @@ export type CarouselProps<
   nextButtonRef: MutableRef<HTMLButtonElement | null>;
   previousButtonRef: MutableRef<HTMLButtonElement | null>;
   carouselIdRef: MutableRef<string>;
-  items: Array<RecordWithObjectID<TObject>>;
+  items: Array<RecordWithObjectID<TObject> | TrendingFacetHit>;
   itemComponent?: (
     props: RecommendItemComponentProps<RecordWithObjectID<TObject>> &
       TComponentProps
@@ -232,22 +234,41 @@ export function createCarouselComponent({ createElement, Fragment }: Renderer) {
             }
           }}
         >
-          {items.map((item, index) => (
-            <li
-              key={item.objectID}
-              className={cx(cssClasses.item)}
-              aria-roledescription="slide"
-              aria-label={`${index + 1} of ${items.length}`}
-              onClick={() => {
-                sendEvent('click:internal', item, 'Item Clicked');
-              }}
-              onAuxClick={() => {
-                sendEvent('click:internal', item, 'Item Clicked');
-              }}
-            >
-              <ItemComponent item={item} sendEvent={sendEvent} />
-            </li>
-          ))}
+          {items.map((item, index) =>
+            isTrendingFacetHit(item) ? (
+              <li
+                key={item.facetName + item.facetValue}
+                className={cx(cssClasses.item)}
+                aria-roledescription="slide"
+                aria-label={`${index + 1} of ${items.length}`}
+              >
+                <ItemComponent
+                  item={
+                    {
+                      ...item,
+                      objectID: item.facetName + item.facetValue,
+                    } as RecordWithObjectID<any>
+                  }
+                  sendEvent={sendEvent}
+                />
+              </li>
+            ) : (
+              <li
+                key={item.objectID}
+                className={cx(cssClasses.item)}
+                aria-roledescription="slide"
+                aria-label={`${index + 1} of ${items.length}`}
+                onClick={() => {
+                  sendEvent('click:internal', item, 'Item Clicked');
+                }}
+                onAuxClick={() => {
+                  sendEvent('click:internal', item, 'Item Clicked');
+                }}
+              >
+                <ItemComponent item={item} sendEvent={sendEvent} />
+              </li>
+            )
+          )}
         </ol>
 
         <button
diff --git a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
new file mode 100644
index 0000000000..c6a0d987d1
--- /dev/null
+++ b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
@@ -0,0 +1,167 @@
+/** @jsx createElement */
+
+import { cx } from '../lib';
+
+import {
+  createDefaultEmptyComponent,
+  createDefaultHeaderComponent,
+  createDefaultItemComponent,
+} from './recommend-shared';
+
+import type {
+  ComponentProps,
+  RecommendClassNames,
+  RecommendInnerComponentProps,
+  RecommendItemComponentProps,
+  RecommendStatus,
+  RecommendTranslations,
+  RecordWithObjectID,
+  Renderer,
+  SendEventForHits,
+} from '../types';
+import type { TrendingFacetHit as Base } from 'algoliasearch';
+
+export type TrendingFacetHit = Base & {
+  __position: number;
+  __queryID?: string;
+};
+
+type TrendingFacetLayoutProps<TClassNames extends Record<string, string>> = {
+  classNames: TClassNames;
+  itemComponent: (
+    props: RecommendItemComponentProps<TrendingFacetHit>
+  ) => JSX.Element;
+  items: TrendingFacetHit[];
+  sendEvent: SendEventForHits;
+};
+
+export type TrendingFacetsComponentProps<
+  TComponentProps extends Record<string, unknown> = Record<string, unknown>
+> = {
+  itemComponent?: (
+    props: RecommendItemComponentProps<TrendingFacetHit> & TComponentProps
+  ) => JSX.Element;
+  items: TrendingFacetHit[];
+  sendEvent: SendEventForHits;
+  classNames?: Partial<RecommendClassNames>;
+  emptyComponent?: (props: TComponentProps) => JSX.Element;
+  headerComponent?: (
+    props: RecommendInnerComponentProps<TrendingFacetHit> & TComponentProps
+  ) => JSX.Element;
+  status: RecommendStatus;
+  translations?: Partial<RecommendTranslations>;
+  layout?: (
+    props: TrendingFacetLayoutProps<Record<string, string>> & TComponentProps
+  ) => JSX.Element;
+};
+
+export type TrendingFacetsProps<
+  TComponentProps extends Record<string, unknown> = Record<string, unknown>
+> = ComponentProps<'div'> & TrendingFacetsComponentProps<TComponentProps>;
+
+export function createTrendingFacetsComponent({
+  createElement,
+  Fragment,
+}: Renderer) {
+  return function TrendingFacets(userProps: TrendingFacetsProps) {
+    const {
+      classNames = {},
+      emptyComponent: EmptyComponent = createDefaultEmptyComponent({
+        createElement,
+        Fragment,
+      }),
+      headerComponent: HeaderComponent = createDefaultHeaderComponent({
+        createElement,
+        Fragment,
+      }),
+      itemComponent: ItemComponent = createDefaultItemComponent({
+        createElement,
+        Fragment,
+      }),
+      layout: Layout = createListComponent({ createElement, Fragment }),
+      items,
+      status,
+      translations: userTranslations,
+      sendEvent,
+      ...props
+    } = userProps;
+
+    const translations: Required<RecommendTranslations> = {
+      title: 'Trending facets',
+      sliderLabel: 'Trending facets',
+      ...userTranslations,
+    };
+
+    const cssClasses: RecommendClassNames = {
+      root: cx('ais-TrendingFacets', classNames.root),
+      emptyRoot: cx(
+        'ais-TrendingFacets',
+        classNames.root,
+        'ais-TrendingFacets--empty',
+        classNames.emptyRoot,
+        props.className
+      ),
+      title: cx('ais-TrendingFacets-title', classNames.title),
+      container: cx('ais-TrendingFacets-container', classNames.container),
+      list: cx('ais-TrendingFacets-list', classNames.list),
+      item: cx('ais-TrendingFacets-item', classNames.item),
+    };
+
+    if (items.length === 0 && status === 'idle') {
+      return (
+        <section {...props} className={cssClasses.emptyRoot}>
+          <EmptyComponent />
+        </section>
+      );
+    }
+
+    return (
+      <section {...props} className={cssClasses.root}>
+        <HeaderComponent
+          classNames={cssClasses}
+          items={items}
+          translations={translations}
+        />
+
+        <Layout
+          classNames={cssClasses}
+          itemComponent={ItemComponent}
+          items={items}
+          sendEvent={sendEvent}
+        />
+      </section>
+    );
+  };
+}
+
+export function createListComponent({ createElement }: Renderer) {
+  return function List(
+    userProps: TrendingFacetLayoutProps<Partial<RecommendClassNames>>
+  ) {
+    const {
+      classNames = {},
+      itemComponent: ItemComponent,
+      items,
+      sendEvent,
+    } = userProps;
+
+    return (
+      <div className={classNames.container}>
+        <ol className={classNames.list}>
+          {items.map((item) => (
+            <li
+              key={item.facetName + item.facetValue}
+              className={classNames.item}
+            >
+              <ItemComponent item={item} sendEvent={sendEvent} />
+            </li>
+          ))}
+        </ol>
+      </div>
+    );
+  };
+}
+
+export const isTrendingFacetHit = (
+  item: RecordWithObjectID<any> | TrendingFacetHit
+): item is TrendingFacetHit => !item.objectID && 'facetValue' in item;
diff --git a/packages/instantsearch-ui-components/src/components/index.ts b/packages/instantsearch-ui-components/src/components/index.ts
index 034b2b8943..7c389f050b 100644
--- a/packages/instantsearch-ui-components/src/components/index.ts
+++ b/packages/instantsearch-ui-components/src/components/index.ts
@@ -5,3 +5,4 @@ export * from './Hits';
 export * from './LookingSimilar';
 export * from './RelatedProducts';
 export * from './TrendingItems';
+export * from './TrendingFacets';
diff --git a/packages/instantsearch.js/src/connectors/index.ts b/packages/instantsearch.js/src/connectors/index.ts
index f14dcde625..bde58d781c 100644
--- a/packages/instantsearch.js/src/connectors/index.ts
+++ b/packages/instantsearch.js/src/connectors/index.ts
@@ -54,3 +54,5 @@ export { default as connectVoiceSearch } from './voice-search/connectVoiceSearch
 export { default as connectRelevantSort } from './relevant-sort/connectRelevantSort';
 export { default as connectFrequentlyBoughtTogether } from './frequently-bought-together/connectFrequentlyBoughtTogether';
 export { default as connectLookingSimilar } from './looking-similar/connectLookingSimilar';
+export { default as connectTrendingFacets } from './trending-facets/connectTrendingFacets';
+export type { TrendingFacetHit } from './trending-facets/connectTrendingFacets';
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
new file mode 100644
index 0000000000..7d2e449107
--- /dev/null
+++ b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
@@ -0,0 +1,175 @@
+import {
+  createDocumentationMessageGenerator,
+  checkRendering,
+  noop,
+  escapeHits,
+  addAbsolutePosition,
+  addQueryID,
+} from '../../lib/utils';
+
+import type {
+  Connector,
+  TransformItems,
+  Renderer,
+  Unmounter,
+  UnknownWidgetParams,
+  RecommendResponse,
+} from '../../types';
+import type { TrendingFacetHit } from './types';
+
+const withUsage = createDocumentationMessageGenerator({
+  name: 'trending-facets',
+  connector: true,
+});
+
+export type TrendingFacetsRenderState = {
+  /**
+   * The matched recommendations from the Algolia API.
+   */
+  items: TrendingFacetHit[];
+};
+
+export type TrendingFacetsConnectorParams = {
+  /**
+   * The facet attribute to get recommendations for.
+   */
+  facetName: string;
+} & {
+  /**
+   * The number of recommendations to retrieve.
+   */
+  limit?: number;
+  /**
+   * The threshold for the recommendations confidence score (between 0 and 100).
+   */
+  threshold?: number;
+
+  /**
+   * Whether to escape HTML tags from items string values.
+   *
+   * @default true
+   */
+  escapeHTML?: boolean;
+  /**
+   * Function to transform the items passed to the templates.
+   */
+  transformItems?: TransformItems<
+    TrendingFacetHit,
+    { results: RecommendResponse<TrendingFacetHit> }
+  >;
+};
+
+export type TrendingFacetsWidgetDescription = {
+  $$type: 'ais.TrendingFacets';
+  renderState: TrendingFacetsRenderState;
+};
+
+export type TrendingFacetsConnector = Connector<
+  TrendingFacetsWidgetDescription,
+  TrendingFacetsConnectorParams
+>;
+
+export default (function connectTrendingFacets<
+  TWidgetParams extends UnknownWidgetParams
+>(
+  renderFn: Renderer<
+    TrendingFacetsRenderState,
+    TWidgetParams & TrendingFacetsConnectorParams
+  >,
+  unmountFn: Unmounter = noop
+) {
+  checkRendering(renderFn, withUsage());
+
+  return (widgetParams: TWidgetParams & TrendingFacetsConnectorParams) => {
+    const {
+      facetName,
+      limit,
+      threshold,
+      // @MAJOR: this can default to false
+      escapeHTML = true,
+      transformItems = ((items) => items) as NonNullable<
+        TrendingFacetsConnectorParams['transformItems']
+      >,
+    } = widgetParams || {};
+
+    return {
+      dependsOn: 'recommend',
+      $$type: 'ais.TrendingFacets',
+
+      init(initOptions) {
+        renderFn(
+          {
+            ...this.getWidgetRenderState(initOptions),
+            instantSearchInstance: initOptions.instantSearchInstance,
+          },
+          true
+        );
+      },
+
+      render(renderOptions) {
+        const renderState = this.getWidgetRenderState(renderOptions);
+
+        renderFn(
+          {
+            ...renderState,
+            instantSearchInstance: renderOptions.instantSearchInstance,
+          },
+          false
+        );
+      },
+
+      getRenderState(renderState) {
+        return renderState;
+      },
+
+      getWidgetRenderState({ results }) {
+        if (results === null || results === undefined) {
+          return { items: [], widgetParams };
+        }
+
+        if (escapeHTML && results.hits.length > 0) {
+          results.hits = escapeHits(results.hits);
+        }
+
+        const itemsWithAbsolutePosition = addAbsolutePosition(
+          results.hits,
+          0,
+          1
+        );
+
+        const itemsWithAbsolutePositionAndQueryID = addQueryID(
+          itemsWithAbsolutePosition,
+          results.queryID
+        );
+
+        const transformedItems = transformItems(
+          itemsWithAbsolutePositionAndQueryID as TrendingFacetHit[],
+          {
+            results: results as RecommendResponse<TrendingFacetHit>,
+          }
+        );
+
+        return {
+          items: transformedItems,
+          widgetParams,
+        };
+      },
+
+      dispose({ recommendState }) {
+        unmountFn();
+        return recommendState.removeParams(this.$$id!);
+      },
+
+      getWidgetParameters(state) {
+        return state.removeParams(this.$$id!).addTrendingFacets({
+          facetName,
+          maxRecommendations: limit,
+          threshold,
+          $$id: this.$$id!,
+        });
+      },
+    };
+  };
+} satisfies TrendingFacetsConnector);
+
+export type { TrendingFacetHit } from './types';
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/types.ts b/packages/instantsearch.js/src/connectors/trending-facets/types.ts
new file mode 100644
index 0000000000..14861190a4
--- /dev/null
+++ b/packages/instantsearch.js/src/connectors/trending-facets/types.ts
@@ -0,0 +1,6 @@
+import type { TrendingFacetHit as Base } from 'algoliasearch';
+
+export type TrendingFacetHit = Base & {
+  __position: number;
+  __queryID?: string;
+};
diff --git a/packages/instantsearch.js/src/widgets/index.ts b/packages/instantsearch.js/src/widgets/index.ts
index 6fd492c520..fbbd93daa3 100644
--- a/packages/instantsearch.js/src/widgets/index.ts
+++ b/packages/instantsearch.js/src/widgets/index.ts
@@ -55,6 +55,7 @@ export { default as sortBy } from './sort-by/sort-by';
 export { default as stats } from './stats/stats';
 export { default as toggleRefinement } from './toggle-refinement/toggle-refinement';
 export { default as trendingItems } from './trending-items/trending-items';
+export { default as trendingFacets } from './trending-facets/trending-facets';
 export { default as voiceSearch } from './voice-search/voice-search';
 export { default as frequentlyBoughtTogether } from './frequently-bought-together/frequently-bought-together';
 export { default as lookingSimilar } from './looking-similar/looking-similar';
diff --git a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
new file mode 100644
index 0000000000..588dbf0348
--- /dev/null
+++ b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
@@ -0,0 +1,273 @@
+/** @jsx h */
+
+import { createTrendingFacetsComponent } from 'instantsearch-ui-components';
+import { Fragment, h, render } from 'preact';
+
+import TemplateComponent from '../../components/Template/Template';
+import connectTrendingFacets from '../../connectors/trending-facets/connectTrendingFacets';
+import { prepareTemplateProps } from '../../lib/templating';
+import {
+  getContainerNode,
+  createDocumentationMessageGenerator,
+} from '../../lib/utils';
+
+import type {
+  TrendingFacetsWidgetDescription,
+  TrendingFacetsConnectorParams,
+  TrendingFacetsRenderState,
+  TrendingFacetHit,
+} from '../../connectors/trending-facets/connectTrendingFacets';
+import type { PreparedTemplateProps } from '../../lib/templating';
+import type {
+  Template,
+  WidgetFactory,
+  Renderer,
+  RecommendResponse,
+  TemplateWithBindEvent,
+} from '../../types';
+import type {
+  RecommendClassNames,
+  TrendingFacetsProps as TrendingFacetsUiProps,
+} from 'instantsearch-ui-components';
+
+const withUsage = createDocumentationMessageGenerator({
+  name: 'trending-items',
+});
+
+const TrendingFacets = createTrendingFacetsComponent({
+  createElement: h,
+  Fragment,
+});
+
+type CreateRendererProps = {
+  containerNode: HTMLElement;
+  cssClasses: TrendingFacetsCSSClasses;
+  renderState: {
+    templateProps?: PreparedTemplateProps<TrendingFacetsTemplates>;
+  };
+  templates: TrendingFacetsTemplates;
+};
+
+function createRenderer({
+  renderState,
+  cssClasses,
+  containerNode,
+  templates,
+}: CreateRendererProps): Renderer<
+  TrendingFacetsRenderState,
+  Partial<TrendingFacetsWidgetParams>
+> {
+  return function renderer(
+    { items, results, instantSearchInstance },
+    isFirstRendering
+  ) {
+    if (isFirstRendering) {
+      renderState.templateProps = prepareTemplateProps({
+        defaultTemplates: {} as unknown as Required<TrendingFacetsTemplates>,
+        templatesConfig: instantSearchInstance.templatesConfig,
+        templates,
+      });
+
+      return;
+    }
+
+    const headerComponent = (
+      templates.header
+        ? (data) => (
+            <TemplateComponent
+              {...renderState.templateProps}
+              templateKey="header"
+              rootTagName="fragment"
+              data={{
+                cssClasses: data.classNames,
+                items: data.items,
+              }}
+            />
+          )
+        : undefined
+    ) as TrendingFacetsUiProps['headerComponent'];
+
+    const itemComponent: TrendingFacetsUiProps['itemComponent'] = templates.item
+      ? ({ item, ...rootProps }) => {
+          return (
+            <TemplateComponent
+              {...renderState.templateProps}
+              templateKey="item"
+              rootTagName="fragment"
+              data={item}
+              rootProps={{ ...rootProps }}
+            />
+          );
+        }
+      : undefined;
+
+    const emptyComponent = (
+      templates.empty
+        ? () => (
+            <TemplateComponent
+              {...renderState.templateProps}
+              templateKey="empty"
+              rootTagName="fragment"
+              data={results}
+            />
+          )
+        : undefined
+    ) as TrendingFacetsUiProps['emptyComponent'];
+
+    // @TODO fix data type
+    const layoutComponent = templates.layout
+      ? (data: any) => (
+          <TemplateComponent
+            {...renderState.templateProps}
+            templateKey="layout"
+            rootTagName="fragment"
+            data={{
+              items: data.items,
+              templates: {
+                item: templates.item
+                  ? ({ item }: { item: TrendingFacetHit }) => (
+                      <TemplateComponent
+                        {...renderState.templateProps}
+                        templateKey="item"
+                        rootTagName="fragment"
+                        data={item}
+                      />
+                    )
+                  : undefined,
+              },
+              cssClasses: {
+                list: data.classNames.list,
+                item: data.classNames.item,
+              },
+            }}
+          />
+        )
+      : undefined;
+
+    render(
+      <TrendingFacets
+        items={items}
+        classNames={cssClasses}
+        headerComponent={headerComponent}
+        itemComponent={itemComponent}
+        emptyComponent={emptyComponent}
+        layout={layoutComponent}
+        status={instantSearchInstance.status}
+      />,
+      containerNode
+    );
+  };
+}
+
+export type TrendingFacetsCSSClasses = Partial<RecommendClassNames>;
+
+export type TrendingFacetsTemplates = Partial<{
+  /**
+   * Template to use when there are no results.
+   */
+  empty: Template<RecommendResponse<TrendingFacetHit>>;
+
+  /**
+   * Template to use for the header of the widget.
+   */
+  header: Template<
+    Pick<
+      Parameters<
+        NonNullable<TrendingFacetsUiProps<TrendingFacetHit>['headerComponent']>
+      >[0],
+      'items'
+    > & { cssClasses: RecommendClassNames }
+  >;
+
+  /**
+   * Template to use for each result. This template will receive an object containing a single record.
+   */
+  item: TemplateWithBindEvent<TrendingFacetHit>;
+
+  /**
+   * Template to use to wrap all items.
+   */
+  layout: Template<
+    Pick<
+      Parameters<
+        NonNullable<TrendingFacetsUiProps<TrendingFacetHit>['layout']>
+      >[0],
+      'items'
+    > & {
+      templates: {
+        item: TrendingFacetsUiProps<TrendingFacetHit>['itemComponent'];
+      };
+      cssClasses: Pick<TrendingFacetsCSSClasses, 'list' | 'item'>;
+    }
+  >;
+}>;
+
+type TrendingFacetsWidgetParams = {
+  /**
+   * CSS selector or `HTMLElement` to insert the widget into.
+   */
+  container: string | HTMLElement;
+
+  /**
+   * Templates to customize the widget.
+   */
+  templates?: TrendingFacetsTemplates;
+
+  /**
+   * CSS classes to add to the widget elements.
+   */
+  cssClasses?: TrendingFacetsCSSClasses;
+};
+
+export type TrendingFacetsWidget = WidgetFactory<
+  TrendingFacetsWidgetDescription & {
+    $$widgetType: 'ais.TrendingFacets';
+  },
+  TrendingFacetsConnectorParams,
+  TrendingFacetsWidgetParams
+>;
+
+export default (function trendingFacets(
+  widgetParams: TrendingFacetsWidgetParams & TrendingFacetsConnectorParams
+) {
+  const {
+    container,
+    facetName,
+    limit,
+    threshold,
+    escapeHTML,
+    transformItems,
+    templates = {},
+    cssClasses = {},
+  } = widgetParams || {};
+
+  if (!container) {
+    throw new Error(withUsage('The `container` option is required.'));
+  }
+
+  const containerNode = getContainerNode(container);
+
+  const specializedRenderer = createRenderer({
+    containerNode,
+    cssClasses,
+    renderState: {},
+    templates,
+  });
+
+  const makeWidget = connectTrendingFacets(specializedRenderer, () =>
+    render(null, containerNode)
+  );
+
+  const facetParameters = { facetName };
+
+  return {
+    ...makeWidget({
+      ...facetParameters,
+      limit,
+      threshold,
+      escapeHTML,
+      transformItems,
+    }),
+    $$widgetType: 'ais.TrendingFacets',
+  };
+} satisfies TrendingFacetsWidget);
diff --git a/packages/react-instantsearch-core/src/connectors/useTrendingFacets.ts b/packages/react-instantsearch-core/src/connectors/useTrendingFacets.ts
new file mode 100644
index 0000000000..8c3d6d50da
--- /dev/null
+++ b/packages/react-instantsearch-core/src/connectors/useTrendingFacets.ts
@@ -0,0 +1,26 @@
+import connectTrendingFacets from 'instantsearch.js/es/connectors/trending-facets/connectTrendingFacets';
+
+import { useConnector } from '../hooks/useConnector';
+
+import type { AdditionalWidgetProperties } from '../hooks/useConnector';
+import type {
+  TrendingFacetsConnector,
+  TrendingFacetsConnectorParams,
+  TrendingFacetsWidgetDescription,
+} from 'instantsearch.js/es/connectors/trending-facets/connectTrendingFacets';
+
+export type UseTrendingFacetsProps = TrendingFacetsConnectorParams;
+
+export function useTrendingFacets(
+  props?: UseTrendingFacetsProps,
+  additionalWidgetProperties?: AdditionalWidgetProperties
+) {
+  return useConnector<
+    TrendingFacetsConnectorParams,
+    TrendingFacetsWidgetDescription
+  >(
+    connectTrendingFacets as TrendingFacetsConnector,
+    props,
+    additionalWidgetProperties
+  );
+}
diff --git a/packages/react-instantsearch-core/src/index.ts b/packages/react-instantsearch-core/src/index.ts
index db206dfe8a..6caebddb29 100644
--- a/packages/react-instantsearch-core/src/index.ts
+++ b/packages/react-instantsearch-core/src/index.ts
@@ -29,6 +29,7 @@ export * from './connectors/useSortBy';
 export * from './connectors/useStats';
 export * from './connectors/useToggleRefinement';
 export * from './connectors/useTrendingItems';
+export * from './connectors/useTrendingFacets';
 export * from './connectors/useLookingSimilar';
 export * from './hooks/useConnector';
 export * from './hooks/useInstantSearch';
diff --git a/packages/react-instantsearch/src/widgets/TrendingFacets.tsx b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
new file mode 100644
index 0000000000..645a02bd66
--- /dev/null
+++ b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
@@ -0,0 +1,92 @@
+import { createTrendingFacetsComponent } from 'instantsearch-ui-components';
+import React, { createElement, Fragment, useMemo } from 'react';
+import { useInstantSearch, useTrendingFacets } from 'react-instantsearch-core';
+
+import type {
+  TrendingFacetsProps as TrendingFacetsUiComponentProps,
+  Pragma,
+} from 'instantsearch-ui-components';
+import type { UseTrendingFacetsProps } from 'react-instantsearch-core';
+
+type UiProps = Pick<
+  TrendingFacetsUiComponentProps,
+  | 'items'
+  | 'itemComponent'
+  | 'headerComponent'
+  | 'emptyComponent'
+  | 'layout'
+  | 'status'
+  | 'sendEvent'
+>;
+
+export type TrendingFacetsProps = Omit<
+  TrendingFacetsUiComponentProps,
+  keyof UiProps
+> &
+  UseTrendingFacetsProps & {
+    itemComponent?: TrendingFacetsUiComponentProps['itemComponent'];
+    headerComponent?: TrendingFacetsUiComponentProps['headerComponent'];
+    emptyComponent?: TrendingFacetsUiComponentProps['emptyComponent'];
+    layoutComponent?: TrendingFacetsUiComponentProps['layout'];
+  };
+
+const TrendingFacetsUiComponent = createTrendingFacetsComponent({
+  createElement: createElement as Pragma,
+  Fragment,
+});
+
+export function TrendingFacets({
+  facetName,
+  limit,
+  threshold,
+  escapeHTML,
+  transformItems,
+  itemComponent,
+  headerComponent,
+  emptyComponent,
+  layoutComponent,
+  ...props
+}: TrendingFacetsProps) {
+  const { status } = useInstantSearch();
+  const { items } = useTrendingFacets(
+    {
+      facetName,
+      limit,
+      threshold,
+      escapeHTML,
+      transformItems,
+    },
+    { $$widgetType: 'ais.TrendingFacets' }
+  );
+
+  const layout: typeof layoutComponent = layoutComponent
+    ? (layoutProps) =>
+        layoutComponent({
+          ...layoutProps,
+          classNames: {
+            list: layoutProps.classNames.list,
+            item: layoutProps.classNames.item,
+          },
+        })
+    : undefined;
+
+  const _itemComponent: typeof itemComponent = useMemo(
+    () =>
+      itemComponent
+        ? (itemProps) => itemComponent({ ...itemProps })
+        : undefined,
+    [itemComponent]
+  );
+
+  const uiProps: UiProps = {
+    items,
+    itemComponent: _itemComponent,
+    headerComponent,
+    emptyComponent,
+    layout,
+    status,
+    sendEvent: () => {},
+  };
+
+  return <TrendingFacetsUiComponent {...props} {...uiProps} />;
+}
diff --git a/packages/react-instantsearch/src/widgets/index.ts b/packages/react-instantsearch/src/widgets/index.ts
index a4316e302a..f7a9c9bb0d 100644
--- a/packages/react-instantsearch/src/widgets/index.ts
+++ b/packages/react-instantsearch/src/widgets/index.ts
@@ -19,4 +19,5 @@ export * from './SortBy';
 export * from './Stats';
 export * from './ToggleRefinement';
 export * from './TrendingItems';
+export * from './TrendingFacets';
 export * from './LookingSimilar';

From bc997e51f78f839300288f95f5b83a5c6dfae618 Mon Sep 17 00:00:00 2001
From: Raed <raed.chammam@algolia.com>
Date: Mon, 10 Feb 2025 08:29:02 +0100
Subject: [PATCH 2/4] fix tests

---
 .../src/components/TrendingFacets.tsx                        | 2 +-
 .../src/connectors/trending-facets/connectTrendingFacets.ts  | 4 ++--
 .../instantsearch.js/src/connectors/trending-facets/types.ts | 2 +-
 .../src/widgets/trending-facets/trending-facets.tsx          | 5 +++--
 packages/react-instantsearch/src/widgets/TrendingFacets.tsx  | 2 +-
 .../src/widgets/__tests__/__utils__/all-widgets.tsx          | 3 +++
 .../src/widgets/__tests__/all-widgets.test.tsx               | 5 +++++
 7 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
index c6a0d987d1..02c8fde66d 100644
--- a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
+++ b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
@@ -19,7 +19,7 @@ import type {
   Renderer,
   SendEventForHits,
 } from '../types';
-import type { TrendingFacetHit as Base } from 'algoliasearch';
+import type { TrendingFacetHit as Base } from 'algoliasearch/lite';
 
 export type TrendingFacetHit = Base & {
   __position: number;
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
index 7d2e449107..14b0ae9e8a 100644
--- a/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
+++ b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
@@ -60,7 +60,7 @@ export type TrendingFacetsConnectorParams = {
 };
 
 export type TrendingFacetsWidgetDescription = {
-  $$type: 'ais.TrendingFacets';
+  $$type: 'ais.trendingFacets';
   renderState: TrendingFacetsRenderState;
 };
 
@@ -94,7 +94,7 @@ export default (function connectTrendingFacets<
 
     return {
       dependsOn: 'recommend',
-      $$type: 'ais.TrendingFacets',
+      $$type: 'ais.trendingFacets',
 
       init(initOptions) {
         renderFn(
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/types.ts b/packages/instantsearch.js/src/connectors/trending-facets/types.ts
index 14861190a4..0b23dc1a0c 100644
--- a/packages/instantsearch.js/src/connectors/trending-facets/types.ts
+++ b/packages/instantsearch.js/src/connectors/trending-facets/types.ts
@@ -1,4 +1,4 @@
-import type { TrendingFacetHit as Base } from 'algoliasearch';
+import type { TrendingFacetHit as Base } from 'algoliasearch/lite';
 
 export type TrendingFacetHit = Base & {
   __position: number;
diff --git a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
index 588dbf0348..0eb6d2e976 100644
--- a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
+++ b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
@@ -153,6 +153,7 @@ function createRenderer({
         emptyComponent={emptyComponent}
         layout={layoutComponent}
         status={instantSearchInstance.status}
+        sendEvent={() => {}}
       />,
       containerNode
     );
@@ -221,7 +222,7 @@ type TrendingFacetsWidgetParams = {
 
 export type TrendingFacetsWidget = WidgetFactory<
   TrendingFacetsWidgetDescription & {
-    $$widgetType: 'ais.TrendingFacets';
+    $$widgetType: 'ais.trendingFacets';
   },
   TrendingFacetsConnectorParams,
   TrendingFacetsWidgetParams
@@ -268,6 +269,6 @@ export default (function trendingFacets(
       escapeHTML,
       transformItems,
     }),
-    $$widgetType: 'ais.TrendingFacets',
+    $$widgetType: 'ais.trendingFacets',
   };
 } satisfies TrendingFacetsWidget);
diff --git a/packages/react-instantsearch/src/widgets/TrendingFacets.tsx b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
index 645a02bd66..35afb5e8ae 100644
--- a/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
+++ b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
@@ -56,7 +56,7 @@ export function TrendingFacets({
       escapeHTML,
       transformItems,
     },
-    { $$widgetType: 'ais.TrendingFacets' }
+    { $$widgetType: 'ais.trendingFacets' }
   );
 
   const layout: typeof layoutComponent = layoutComponent
diff --git a/packages/react-instantsearch/src/widgets/__tests__/__utils__/all-widgets.tsx b/packages/react-instantsearch/src/widgets/__tests__/__utils__/all-widgets.tsx
index ea4b7ecdfe..8110d88ff6 100644
--- a/packages/react-instantsearch/src/widgets/__tests__/__utils__/all-widgets.tsx
+++ b/packages/react-instantsearch/src/widgets/__tests__/__utils__/all-widgets.tsx
@@ -96,6 +96,9 @@ function Widget<TWidget extends SingleWidget>({
     case 'LookingSimilar': {
       return <widget.Component objectIDs={['1']} {...props} />;
     }
+    case 'TrendingFacets': {
+      return <widget.Component facetName="foobar" {...props} />;
+    }
     default: {
       return <widget.Component {...props} />;
     }
diff --git a/packages/react-instantsearch/src/widgets/__tests__/all-widgets.test.tsx b/packages/react-instantsearch/src/widgets/__tests__/all-widgets.test.tsx
index 8fbab91543..e01324c5e0 100644
--- a/packages/react-instantsearch/src/widgets/__tests__/all-widgets.test.tsx
+++ b/packages/react-instantsearch/src/widgets/__tests__/all-widgets.test.tsx
@@ -150,6 +150,11 @@ describe('widgets', () => {
           "$$widgetType": "ais.trendingItems",
           "name": "TrendingItems",
         },
+        {
+          "$$type": "ais.trendingFacets",
+          "$$widgetType": "ais.trendingFacets",
+          "name": "TrendingFacets",
+        },
         {
           "$$type": "ais.lookingSimilar",
           "$$widgetType": "ais.lookingSimilar",

From be5ab5caaa7297765df49f5ab1c0bff67bb57d69 Mon Sep 17 00:00:00 2001
From: Raed <raed.chammam@algolia.com>
Date: Mon, 10 Feb 2025 11:08:46 +0100
Subject: [PATCH 3/4] fix v4 type issue (for real?)

---
 .../types/algoliasearch.d.ts                   | 18 ++++++++++++++++++
 .../src/components/Carousel.tsx                |  3 ++-
 .../src/components/TrendingFacets.tsx          |  7 +------
 .../instantsearch.js/src/connectors/index.ts   |  1 -
 .../trending-facets/connectTrendingFacets.ts   |  4 +---
 .../src/connectors/trending-facets/types.ts    |  6 ------
 .../trending-facets/trending-facets.tsx        |  2 +-
 7 files changed, 23 insertions(+), 18 deletions(-)
 delete mode 100644 packages/instantsearch.js/src/connectors/trending-facets/types.ts

diff --git a/packages/algoliasearch-helper/types/algoliasearch.d.ts b/packages/algoliasearch-helper/types/algoliasearch.d.ts
index 01b7972c0e..62fdfda921 100644
--- a/packages/algoliasearch-helper/types/algoliasearch.d.ts
+++ b/packages/algoliasearch-helper/types/algoliasearch.d.ts
@@ -182,6 +182,24 @@ export type RecommendResponses<T> = PickForClient<{
   v5: AlgoliaSearch.GetRecommendationsResponse;
 }>;
 
+export type TrendingFacetHit = PickForClient<{
+  v3: any;
+  // @ts-ignore
+  v4: {
+    readonly _score: number;
+    readonly facetName: string;
+    readonly facetValue: string;
+  } & {
+    __position: number;
+    __queryID?: string;
+  };
+  // @ts-ignore
+  v5: RecommendClient.TrendingFacetHit & {
+    __position: number;
+    __queryID?: string;
+  };
+}>;
+
 // We remove `indexName` from the Recommend query types as the helper
 // will fill in this value before sending the queries
 type _OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
diff --git a/packages/instantsearch-ui-components/src/components/Carousel.tsx b/packages/instantsearch-ui-components/src/components/Carousel.tsx
index 46d77752b7..58f2d5b906 100644
--- a/packages/instantsearch-ui-components/src/components/Carousel.tsx
+++ b/packages/instantsearch-ui-components/src/components/Carousel.tsx
@@ -1,4 +1,5 @@
 /** @jsx createElement */
+
 import { cx } from '../lib';
 
 import { createDefaultItemComponent } from './recommend-shared';
@@ -12,7 +13,7 @@ import type {
   Renderer,
   SendEventForHits,
 } from '../types';
-import type { TrendingFacetHit } from './TrendingFacets';
+import type { TrendingFacetHit } from 'algoliasearch';
 
 export type CarouselProps<
   TObject,
diff --git a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
index 02c8fde66d..b075aeda6b 100644
--- a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
+++ b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
@@ -19,12 +19,7 @@ import type {
   Renderer,
   SendEventForHits,
 } from '../types';
-import type { TrendingFacetHit as Base } from 'algoliasearch/lite';
-
-export type TrendingFacetHit = Base & {
-  __position: number;
-  __queryID?: string;
-};
+import type { TrendingFacetHit } from 'algoliasearch';
 
 type TrendingFacetLayoutProps<TClassNames extends Record<string, string>> = {
   classNames: TClassNames;
diff --git a/packages/instantsearch.js/src/connectors/index.ts b/packages/instantsearch.js/src/connectors/index.ts
index bde58d781c..dbaec3355c 100644
--- a/packages/instantsearch.js/src/connectors/index.ts
+++ b/packages/instantsearch.js/src/connectors/index.ts
@@ -55,4 +55,3 @@ export { default as connectRelevantSort } from './relevant-sort/connectRelevantS
 export { default as connectFrequentlyBoughtTogether } from './frequently-bought-together/connectFrequentlyBoughtTogether';
 export { default as connectLookingSimilar } from './looking-similar/connectLookingSimilar';
 export { default as connectTrendingFacets } from './trending-facets/connectTrendingFacets';
-export type { TrendingFacetHit } from './trending-facets/connectTrendingFacets';
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
index 14b0ae9e8a..a799276a5a 100644
--- a/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
+++ b/packages/instantsearch.js/src/connectors/trending-facets/connectTrendingFacets.ts
@@ -14,8 +14,8 @@ import type {
   Unmounter,
   UnknownWidgetParams,
   RecommendResponse,
+  TrendingFacetHit,
 } from '../../types';
-import type { TrendingFacetHit } from './types';
 
 const withUsage = createDocumentationMessageGenerator({
   name: 'trending-facets',
@@ -171,5 +171,3 @@ export default (function connectTrendingFacets<
     };
   };
 } satisfies TrendingFacetsConnector);
-
-export type { TrendingFacetHit } from './types';
diff --git a/packages/instantsearch.js/src/connectors/trending-facets/types.ts b/packages/instantsearch.js/src/connectors/trending-facets/types.ts
deleted file mode 100644
index 0b23dc1a0c..0000000000
--- a/packages/instantsearch.js/src/connectors/trending-facets/types.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import type { TrendingFacetHit as Base } from 'algoliasearch/lite';
-
-export type TrendingFacetHit = Base & {
-  __position: number;
-  __queryID?: string;
-};
diff --git a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
index 0eb6d2e976..3f6e8cd3ba 100644
--- a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
+++ b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
@@ -15,7 +15,6 @@ import type {
   TrendingFacetsWidgetDescription,
   TrendingFacetsConnectorParams,
   TrendingFacetsRenderState,
-  TrendingFacetHit,
 } from '../../connectors/trending-facets/connectTrendingFacets';
 import type { PreparedTemplateProps } from '../../lib/templating';
 import type {
@@ -24,6 +23,7 @@ import type {
   Renderer,
   RecommendResponse,
   TemplateWithBindEvent,
+  TrendingFacetHit,
 } from '../../types';
 import type {
   RecommendClassNames,

From 9fb46908e54003b00173b3e99f1e534e4297da0e Mon Sep 17 00:00:00 2001
From: Raed <raed.chammam@algolia.com>
Date: Tue, 18 Feb 2025 13:35:39 +0100
Subject: [PATCH 4/4] make itemComponent required in js

---
 examples/js/getting-started/src/app.js        | 74 -------------------
 examples/react/getting-started/src/App.tsx    |  5 ++
 .../src/components/Carousel.tsx               |  2 +-
 .../src/components/TrendingFacets.tsx         | 10 +--
 .../src/types/Recommend.ts                    | 18 +++++
 .../trending-facets/trending-facets.tsx       | 15 ++--
 .../src/widgets/TrendingFacets.tsx            | 14 +---
 7 files changed, 36 insertions(+), 102 deletions(-)
 delete mode 100644 examples/js/getting-started/src/app.js

diff --git a/examples/js/getting-started/src/app.js b/examples/js/getting-started/src/app.js
deleted file mode 100644
index 1aff8d1171..0000000000
--- a/examples/js/getting-started/src/app.js
+++ /dev/null
@@ -1,74 +0,0 @@
-import { liteClient as algoliasearch } from 'algoliasearch/lite';
-import instantsearch from 'instantsearch.js';
-import { carousel } from 'instantsearch.js/es/templates';
-import {
-  configure,
-  hits,
-  pagination,
-  panel,
-  refinementList,
-  searchBox,
-  trendingFacets,
-} from 'instantsearch.js/es/widgets';
-
-import 'instantsearch.css/themes/satellite.css';
-
-const searchClient = algoliasearch(
-  'latency',
-  '6be0576ff61c053d5f9a3225e2a90f76'
-);
-
-const search = instantsearch({
-  indexName: 'instant_search',
-  searchClient,
-  insights: true,
-});
-
-search.addWidgets([
-  searchBox({
-    container: '#searchbox',
-  }),
-  hits({
-    container: '#hits',
-    templates: {
-      item: (hit, { html, components }) => html`
-        <article>
-          <h1>
-            <a href="/products.html?pid=${hit.objectID}"
-              >${components.Highlight({ hit, attribute: 'name' })}</a
-            >
-          </h1>
-          <p>${components.Highlight({ hit, attribute: 'description' })}</p>
-          <a href="/products.html?pid=${hit.objectID}">See product</a>
-        </article>
-      `,
-    },
-  }),
-  configure({
-    hitsPerPage: 8,
-  }),
-  panel({
-    templates: { header: 'brand' },
-  })(refinementList)({
-    container: '#brand-list',
-    attribute: 'brand',
-  }),
-  pagination({
-    container: '#pagination',
-  }),
-  trendingFacets({
-    container: '#trending',
-    limit: 6,
-    facetName: 'brand',
-    templates: {
-      item: (item, { html }) => html`
-        <div>
-          <h2>${item.facetName}: ${item.facetValue}</h2>
-        </div>
-      `,
-      layout: carousel(),
-    },
-  }),
-]);
-
-search.start();
diff --git a/examples/react/getting-started/src/App.tsx b/examples/react/getting-started/src/App.tsx
index 870229ae6f..dfd6ad741d 100644
--- a/examples/react/getting-started/src/App.tsx
+++ b/examples/react/getting-started/src/App.tsx
@@ -65,6 +65,11 @@ export function App() {
                   facetName="brand"
                   limit={6}
                   layoutComponent={Carousel}
+                  itemComponent={({ item }) => (
+                    <div>
+                      {item.facetName}:{item.facetValue}
+                    </div>
+                  )}
                 />
               </div>
             </div>
diff --git a/packages/instantsearch-ui-components/src/components/Carousel.tsx b/packages/instantsearch-ui-components/src/components/Carousel.tsx
index 58f2d5b906..2ced71318a 100644
--- a/packages/instantsearch-ui-components/src/components/Carousel.tsx
+++ b/packages/instantsearch-ui-components/src/components/Carousel.tsx
@@ -12,8 +12,8 @@ import type {
   RecordWithObjectID,
   Renderer,
   SendEventForHits,
+  TrendingFacetHit,
 } from '../types';
-import type { TrendingFacetHit } from 'algoliasearch';
 
 export type CarouselProps<
   TObject,
diff --git a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
index b075aeda6b..f97d63077d 100644
--- a/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
+++ b/packages/instantsearch-ui-components/src/components/TrendingFacets.tsx
@@ -5,7 +5,6 @@ import { cx } from '../lib';
 import {
   createDefaultEmptyComponent,
   createDefaultHeaderComponent,
-  createDefaultItemComponent,
 } from './recommend-shared';
 
 import type {
@@ -18,8 +17,8 @@ import type {
   RecordWithObjectID,
   Renderer,
   SendEventForHits,
+  TrendingFacetHit,
 } from '../types';
-import type { TrendingFacetHit } from 'algoliasearch';
 
 type TrendingFacetLayoutProps<TClassNames extends Record<string, string>> = {
   classNames: TClassNames;
@@ -33,7 +32,7 @@ type TrendingFacetLayoutProps<TClassNames extends Record<string, string>> = {
 export type TrendingFacetsComponentProps<
   TComponentProps extends Record<string, unknown> = Record<string, unknown>
 > = {
-  itemComponent?: (
+  itemComponent: (
     props: RecommendItemComponentProps<TrendingFacetHit> & TComponentProps
   ) => JSX.Element;
   items: TrendingFacetHit[];
@@ -69,10 +68,7 @@ export function createTrendingFacetsComponent({
         createElement,
         Fragment,
       }),
-      itemComponent: ItemComponent = createDefaultItemComponent({
-        createElement,
-        Fragment,
-      }),
+      itemComponent: ItemComponent,
       layout: Layout = createListComponent({ createElement, Fragment }),
       items,
       status,
diff --git a/packages/instantsearch-ui-components/src/types/Recommend.ts b/packages/instantsearch-ui-components/src/types/Recommend.ts
index be43ddf7fb..0c39f36f43 100644
--- a/packages/instantsearch-ui-components/src/types/Recommend.ts
+++ b/packages/instantsearch-ui-components/src/types/Recommend.ts
@@ -100,3 +100,21 @@ export type RecommendItemComponentProps<TObject> = {
 
 // @TODO: use instantsearch status instead
 export type RecommendStatus = 'idle' | 'loading' | 'stalled' | 'error';
+
+// for convenience, redefined here from instantsearch
+export type TrendingFacetHit = {
+  /**
+   * Recommendation score.
+   */
+  _score: number;
+
+  /**
+   * Facet attribute. To be used in combination with `facetValue`. If specified, only recommendations matching the facet filter will be returned.
+   */
+  facetName: string;
+
+  /**
+   * Facet value. To be used in combination with `facetName`. If specified, only recommendations matching the facet filter will be returned.
+   */
+  facetValue: string;
+};
diff --git a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
index 3f6e8cd3ba..7cf8c708ec 100644
--- a/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
+++ b/packages/instantsearch.js/src/widgets/trending-facets/trending-facets.tsx
@@ -99,7 +99,7 @@ function createRenderer({
             />
           );
         }
-      : undefined;
+      : () => <div></div>;
 
     const emptyComponent = (
       templates.empty
@@ -180,11 +180,6 @@ export type TrendingFacetsTemplates = Partial<{
     > & { cssClasses: RecommendClassNames }
   >;
 
-  /**
-   * Template to use for each result. This template will receive an object containing a single record.
-   */
-  item: TemplateWithBindEvent<TrendingFacetHit>;
-
   /**
    * Template to use to wrap all items.
    */
@@ -201,7 +196,9 @@ export type TrendingFacetsTemplates = Partial<{
       cssClasses: Pick<TrendingFacetsCSSClasses, 'list' | 'item'>;
     }
   >;
-}>;
+}> & {
+  item: TemplateWithBindEvent<TrendingFacetHit>;
+};
 
 type TrendingFacetsWidgetParams = {
   /**
@@ -212,7 +209,7 @@ type TrendingFacetsWidgetParams = {
   /**
    * Templates to customize the widget.
    */
-  templates?: TrendingFacetsTemplates;
+  templates: TrendingFacetsTemplates;
 
   /**
    * CSS classes to add to the widget elements.
@@ -238,7 +235,7 @@ export default (function trendingFacets(
     threshold,
     escapeHTML,
     transformItems,
-    templates = {},
+    templates,
     cssClasses = {},
   } = widgetParams || {};
 
diff --git a/packages/react-instantsearch/src/widgets/TrendingFacets.tsx b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
index 35afb5e8ae..573260af0f 100644
--- a/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
+++ b/packages/react-instantsearch/src/widgets/TrendingFacets.tsx
@@ -1,5 +1,5 @@
 import { createTrendingFacetsComponent } from 'instantsearch-ui-components';
-import React, { createElement, Fragment, useMemo } from 'react';
+import React, { createElement, Fragment } from 'react';
 import { useInstantSearch, useTrendingFacets } from 'react-instantsearch-core';
 
 import type {
@@ -24,7 +24,7 @@ export type TrendingFacetsProps = Omit<
   keyof UiProps
 > &
   UseTrendingFacetsProps & {
-    itemComponent?: TrendingFacetsUiComponentProps['itemComponent'];
+    itemComponent: TrendingFacetsUiComponentProps['itemComponent'];
     headerComponent?: TrendingFacetsUiComponentProps['headerComponent'];
     emptyComponent?: TrendingFacetsUiComponentProps['emptyComponent'];
     layoutComponent?: TrendingFacetsUiComponentProps['layout'];
@@ -70,17 +70,9 @@ export function TrendingFacets({
         })
     : undefined;
 
-  const _itemComponent: typeof itemComponent = useMemo(
-    () =>
-      itemComponent
-        ? (itemProps) => itemComponent({ ...itemProps })
-        : undefined,
-    [itemComponent]
-  );
-
   const uiProps: UiProps = {
     items,
-    itemComponent: _itemComponent,
+    itemComponent,
     headerComponent,
     emptyComponent,
     layout,