# Feed Widget (React)

> Source: https://docs.recombee.com/widget-sdks/feed-widget-react

> For the complete documentation index, see [llms.txt](/llms.txt).

**Table of contents**

* [ Installation ](#install)
* [ Client Initialization ](#client-initialization)  
   * [ Providing User ID ](#providing-user-id)
* [ Basic Example ](#basic-example)
* [ Custom CSS ](#custom-css)
* [ Custom Templates ](#custom-templates)
* [ Overriding Base Classes ](#overriding-base-classes)
* [ Composite Recommendations ](#composite-recommendations)
* [API Reference](#api)  
   * [FeedWidget](#api/FeedWidget)  
   * [FeedWidgetProps](#api/FeedWidgetProps)  
   * [FeedWidgetState](#api/FeedWidgetState)  
   * [DefaultItem](#api/DefaultItem)  
   * [DefaultItemProps](#api/DefaultItemProps)  
   * [ItemImage](#api/ItemImage)  
   * [ItemImageProps](#api/ItemImageProps)  
   * [Recommendation](#api/Recommendation)  
   * [addRecommIdQueryParam](#api/addRecommIdQueryParam)  
   * [CreateRequestFunction](#api/CreateRequestFunction)  
   * [FetchContentOptions](#api/FetchContentOptions)

# Feed Widget (React)

> A React component widget that creates a personalized, scrollable feed of item recommendations, designed for continuous content discovery.

Use this library when you want to render a widget and you are using React and JSX in your project.

This widget library is version 0.2.15 and the API can change. Please specify exact version when installing.

## Installation

Install `@recombee/feed-widget-react@0.2.15` and `recombee-js-api-client`packages using your preferred NPM package manager. This example is using`pnpm`.

```
pnpm add @recombee/feed-widget-react@0.2.15 recombee-js-api-client

```

Always remember to apply the default CSS file distributed alongside the widget library, as shown in the examples.

## Client Initialization

The widget loads recommendation data using [Recombee API Client](/js_client). Here is how to initialize the client with necessary configuration for a specific database:

```
import {  } from "recombee-js-api-client";

const  = "[database-id]";
const  = "[database-public-token]";
const  = "[database-region]";

export const  = new (, , {
  : ,
});

```

The Database Public Token can be found in the Admin UI[Database Settings Page](https://admin.recombee.com/go-to-database/settings).

The widget also needs to be provided a `createRequest` function, which instantiates a client request class to define which data to pull from the database. Use Scenario ID which can be found on Admin GUI[Database Scenarios Page](https://admin.recombee.com/go-to-database/scenarios).

Please ensure that you provide the user ID (typically obtained from your existing user tracking system), along with other relevant parameters - such as an item ID or [Item Segment](/segmentations) ID - depending on the specific type of recommendation request. See the[Providing User ID](#providing-user-id) section for details on how to obtain user ID in specific cases.

```
import { type  } from "@recombee/carousel-widget-react";
import {  } from "recombee-js-api-client";

const :  = ({  }) => {
  const  = "recommend-items-to-user";
  return new (userId, , {
    : ,
    : true,
    : true,
  });
};

```

### Providing User ID

Each visitor of your website should be identified by a user identificator (`userId`) to correlate user activity and deliver best possible recommendation performance. The `userId` should preferrably originate from your user's account details when the user is authenticated or as some session-persistent random ID when they are anonymous. The SDK provides utility which generates random user id and saves it to a cookie to cover the latter case:

```
import { type  } from "@recombee/carousel-widget-react";
import {  } from "recombee-js-api-client";
import {  } from "@recombee/carousel-widget-react";

let : string | undefined;
if (authenticatedUserId) {
   = authenticatedUserId;
} else {
   = .();
}

const :  = ({  }) => {
  const  = "recommend-items-to-user";
  return new (, , {
    : ,
    : true,
    : true,
  });
};

```

## Basic Example

The widget in this example uses the [DefaultItem](#api/DefaultItem) component to render each recommendation in a consistent layout.

The resulting widget is inserted into the element specified by the`container` field.

Values of the recommended items - such as title, image URL, or link URL - are obtained from the API response and accessed via `props.result?.values`.

Ensure that [returnProperties: true](/api#recommend-items-to-user-param-returnProperties) is set in the request, and optionally use[includedProperties](/api#recommend-items-to-user-param-includedProperties)to control which item properties are returned.

```
import {
  ,
  ,
  ,
  ,
} from "@recombee/feed-widget-react";
import "@recombee/feed-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="click"
      ={1}
      ={2}
      ="min-h-[260px]"
      ={() => (
        <
          ={(
            .?.?.link,
            ..,
          )}
          ={
            <
              ={`${.?.?.images?.[0]}`}
              ={600}
              ={400}
            />
          }
          ={`${.?.?.genres?.join(", ")}`}
          ={`${.?.?.title}`}
          ={`${.?.?.year}`}
        />
      )}
      ={() => (
        < ="flex justify-center p-2">
          <
            ="me-2 mb-2 rounded-lg bg-[#3f91ff] px-5 py-2.5 text-sm font-medium text-white focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
            ={..}
          >
            More
          </>
        </>
      )}
    />
  );
};

```

## Custom CSS

Recombee Widgets are designed to be styling-agnostic. You can fully customize their appearance using your own CSS by passing class names through customization properties.

In these docs examples, we use utility classes from [Tailwind CSS](https://tailwindcss.com/) for styling.

Class names for internal elements and custom components are passed as props and applied by the widget during rendering. The default structure of the_Basic Example_ widget is illustrated below (pseudo-code):

```
<div class="{className}">
  <div class="{contentClassName}">
    <div class="{itemWrapperClassName}">
      <ItemComponent />
    </div>
    <div class="{itemWrapperClassName}">
      <ItemComponent />
    </div>
    <div class="{itemWrapperClassName}">
      <ItemComponent />
    </div>
    ... more items ...
  </div>
  <LoadMoreTriggerComponent />
</div>

```

This is especially handy for understanding how to customize the widget to its full potential.

### Setting own classes

```
import {
  ,
  ,
  ,
  ,
} from "@recombee/feed-widget-react";
import "@recombee/feed-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="click"
      ="grid-cols-[repeat(auto-fill,minmax(200px,1fr))] p-3 gap-2 overflow-hidden text-[#282b30] rounded-lg bg-white border border-[#ededed] dark:border-none dark:bg-transparent dark:text-white"
      ="min-h-[260px]"
      ={() => (
        <
          ="border-b border-slate-600"
          ="text-center"
          ={(
            .?.?.link,
            ..,
          )}
          ={
            <
              ={`${.?.?.images?.[0]}`}
              ={600}
              ={400}
            />
          }
          ={`${.?.?.genres?.join(", ")}`}
          ={`${.?.?.title}`}
          ={`${.?.?.year}`}
        />
      )}
      ={() => (
        < ="flex justify-center p-2">
          <
            ="me-2 mb-2 rounded-lg bg-[#3f91ff] px-5 py-2.5 text-sm font-medium text-white focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
            ={..}
          >
            More
          </>
        </>
      )}
    />
  );
};

```

## Custom Templates

Recombee Widgets support full customization of internal components such as the appearance of the recommended items.

You can provide your own components via props like [ItemComponent](#api/ItemComponent) to control the structure, styling, and behavior of the widget.

This flexibility allows you to adapt the widget's appearance and functionality to match your design and user experience requirements.

### Custom Item

```
import { ,  } from "@recombee/feed-widget-react";
import "@recombee/feed-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="click"
      ="min-h-[310px]"
      ={() => (
        < ="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white">
          < ="relative overflow-hidden bg-cover bg-no-repeat">
            <
              ={`${.?.?.images?.[0]}`}
              ={600}
              ={400}
            />
            {.?.?.["genres"]?.includes("drama") && (
              < ="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white">
                Drama
              </>
            )}
            {.?.?.["genres"]?.includes("science_fiction") && (
              < ="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white">
                Sci-Fi
              </>
            )}
          </>
          < ="p-3">
            < ="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]">
              {`${.?.?.genres?.join(", ")}`}
            </>
            < ="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
              {`${.?.?.title}`}
            </>
            < ="line-clamp-4 pb-3 text-base text-[#3f91ff]">
              {`${.?.?.year}`}
            </>
            < ="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]">
              Play
            </>
          </>
        </>
      )}
      ={() => (
        < ="flex justify-center p-2">
          <
            ="me-2 mb-2 rounded-lg bg-[#3f91ff] px-5 py-2.5 text-sm font-medium text-white focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
            ={..}
          >
            More
          </>
        </>
      )}
    />
  );
};

```

## Overriding Base Classes

Some base styles are always applied to ensure the widget maintains the structural shape of a feed.

However, these can be disabled or overridden if needed. Use the[FeedWidgetProps.classNameDisableDefault](#api/FeedWidgetProps.classNameDisableDefault) and related options to opt out of default styling.

```
import {
  ,
  ,
  ,
  ,
} from "@recombee/feed-widget-react";
import "@recombee/feed-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="click"
      ={2}
      ="min-h-[260px]"
      ={() => (
        <
          ={(
            .?.?.link,
            ..,
          )}
          ={
            <
              ={`${.?.?.images?.[0]}`}
              ={600}
              ={400}
            />
          }
          ={`${.?.?.genres?.join(", ")}`}
          ={`${.?.?.title}`}
          ={`${.?.?.year}`}
        />
      )}
      ={() => (
        < ="flex justify-center p-2">
          <
            ="me-2 mb-2 rounded-lg bg-[#3f91ff] px-5 py-2.5 text-sm font-medium text-white focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
            ={..}
          >
            More
          </>
        </>
      )}
    />
  );
};

```

## Composite Recommendations

Widget SDKs can also be used to render [Composite Recommendations](/scenarios#composite-recommendations). A common use case is displaying [dynamic category- or genre-based rails](/scenarios#fully-personalized-homepage) on the homepage, as well as scenarios such as [Because You Watched](/scenarios#because-you-watched-movie-). The CompositeRecommendation request is called from within the[createRequest](/widget-sdks/carousel-widget-react#api/CarouselWidgetProps.createRequest)function. To render the header (for example, the user’s favorite category or the title of the watched movie), implement the[SourceItemComponent](/widget-sdks/carousel-widget-react#api/CarouselWidgetProps.SourceItemComponent).

```
const :  = ({  }) => {
  return new ("top-from-genre-for-you", , {
    : { : true },
  });
};

import {
  ,
  ,
  ,
  ,
} from "@recombee/feed-widget-react";
import "@recombee/feed-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="click"
      ={1}
      ={2}
      ="min-h-[260px]"
      ={({  }) => {
        return  ? (
          < ="my-5">Because you like {?.}</>
        ) : null;
      }}
      ={() => (
        <
          ={(
            .?.?.link,
            ..,
          )}
          ={
            <
              ={`${.?.?.images?.[0]}`}
              ={600}
              ={400}
            />
          }
          ={`${.?.?.genres?.join(", ")}`}
          ={`${.?.?.title}`}
          ={`${.?.?.year}`}
        />
      )}
      ={() => (
        < ="flex justify-center p-2">
          <
            ="me-2 mb-2 rounded-lg bg-[#3f91ff] px-5 py-2.5 text-sm font-medium text-white focus:ring-4 focus:ring-blue-300 focus:outline-hidden"
            ={..}
          >
            More
          </>
        </>
      )}
    />
  );
};

```

## API Reference

const

### FeedWidget

Feed widget component. See [FeedWidgetProps](#api/FeedWidgetProps) for configuration options.

type

### FeedWidgetProps

Configuration options for the Feed widget.

#### Properties

##### apiClient

ApiClient

Instance of Recombee JS API Client. See[Example](#client-initialization).

---

##### createRequest

CreateRequestFunction

Request factory function. See[Quick Example](#client-initialization) or visit[API Reference](/api) for overview of available requests.

---

##### onRecommResponse

WidgetRecommResponseCallback | undefined

Callback function allowing to intercept and inspect recommendation request+response made by widget.

```
import React from "react";
import {  } from "@recombee/carousel-widget-react";

<
  // ...ommited code...
  ={({ ,  }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  }}
/>;

```

---

##### deduplicationPartitionKey

string | undefined

A string key specifying a group of widgets, in which recommendation results will be deduplicated. By default, all widgets belong to a single group so all results from the same database are deduplicated.

---

##### initialRowsCount

number | undefined

Number of rows to load initially.

---

##### loadMoreRowsCount

number | undefined

Number of rows to load on "load more" trigger invocation.

---

##### loadMoreTrigger

"scroll" | "click"

---

##### className

string | undefined

Custom classes of widget wrapper element. See[Custom CSS](#custom-css).

---

##### classNameDisableDefault

boolean | undefined

Disables default classes of widget wrapper element.

There are some default class names with essential styles applied to the widget wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### contentClassName

string | undefined

Custom classes of content wrapper element. See[Custom CSS](#custom-css).

---

##### contentClassNameDisableDefault

boolean | "layout" | undefined

Disables default classes of content wrapper element.

There are some default class names with essential styles applied to the content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### itemWrapperClassName

string | undefined

Custom classes of item wrapper element. See[Custom CSS](#custom-css).

---

##### itemWrapperClassNameDisableDefault

boolean | undefined

Disables default classes of item wrapper element.

There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### ItemComponent

FC<{ state: FeedWidgetState; result: Recommendation; }>

A component rendering a single recommended item.

---

##### LoadMoreTriggerComponent

FC<{ state: FeedWidgetState; }> | (FC<{ state: FeedWidgetState; }> & FC<{ state: FeedWidgetState; }>) | undefined

---

##### SourceItemComponent

FC<{ state: FeedWidgetState; source?: Recommendation | null | undefined; }> | undefined

A component rendering a source recommended item when using Composite Scenario.

---

class

### FeedWidgetState

A Class exposing Feed internal state to be used for customization.

#### Properties

##### sourceItem

Recommendation | null | undefined

Array of items to show in the carousel.

---

##### items

({ type: "ENTITY"; key: string; entity: Recommendation; } | { type: "PLACEHOLDER"; key: string; })\[\]

Array of items to show in the feed

---

##### recommId

string | undefined

Id of recommendation response from which the items originated.

---

##### handleTriggerClick

() => void

Handles clicking on a trigger to load more feed items by a configured increment

---

const

### DefaultItem

Default Item component provided for basic usage.

interface

### DefaultItemProps

Recommended item component properties.

#### Properties

##### className

string | undefined

Custom classes of item wrapper element. See[Custom CSS](#custom-css).

---

##### classNameDisableBase

boolean | undefined

Disables default classes of item wrapper element.

There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### imageWrapperClassName

string | undefined

Custom classes of item image wrapper element. See[Custom CSS](#custom-css).

---

##### imageWrapperClassNameDisableBase

boolean | undefined

Disables default classes of item image wrapper element.

There are some default class names with essential styles applied to the item image wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### contentWrapperClassName

string | undefined

Custom classes of item content element. See[Custom CSS](#custom-css).

---

##### result

Recommendation | undefined

A single item recommedation.

---

##### href

string | null | undefined

Item link URL.

---

##### image

ReactNode

Item Image element.

---

##### labelContent

ReactNode

Item content above title. Sets the entire content of an item aside from an image.

---

##### labelContentWrapperClassName

string | undefined

Custom classes of label content wrapper element. See[Custom CSS](#custom-css).

---

##### labelContentWrapperClassNameDisableBase

boolean | undefined

Disables default classes of label content wrapper element.

There are some default class names with essential styles applied to the label content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### title

ReactNode

Item title.

---

##### titleWrapperClassName

string | undefined

Custom classes of title wrapper element. See[Custom CSS](#custom-css).

---

##### titleWrapperClassNameDisableBase

boolean | undefined

Disables default classes of title wrapper element.

There are some default class names with essential styles applied to the title wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).

---

##### highlightedContent

ReactNode

Item content under title. Sets the entire content of an item aside from an image.

---

##### highlightedContentWrapperClassName

string | undefined

Custom classes of highlighted content wrapper element. See[Custom CSS](#custom-css).

---

##### highlightedContentWrapperClassNameDisableBase

boolean | undefined

Disables default classes of highlighted content wrapper element.

There are some default class names with essential styles applied to the highlighted content wrapper element. This setting disables them as an escape hatch for customization. See[Custom CSS](#custom-css).

---

##### bottomContent

ReactNode

Any custom content to display at the bottom of the item.

---

const

### ItemImage

Item image component

type

### ItemImageProps

Item Image properties

#### Properties

##### src

string | null | undefined

Image URL

---

##### missingImageSrc

string | undefined

URL of an image to display when the main image could not be loaded.

---

##### className

string | undefined

Image wrapper class name

---

##### imgClassName

string | undefined

Image class name

---

##### width

number | undefined

Image width in pixels

---

##### height

number | undefined

Image height in pixels

---

##### verticalAlignment

"top" | "center" | "bottom" | undefined

Image vertical alignment

---

##### horizontalAlignment

"center" | "left" | "right" | undefined

Image horizontal alignment

---

##### fittingAlgorithm

"cover" | "scale\_down" | undefined

Image fitting algorithm

---

type

### Recommendation

Single recommendation item

#### Properties

##### id

string

Item ID

---

##### values

{ \[key: string\]: any; } | undefined

Item properties

---

function

### addRecommIdQueryParam

Utility function to append `recombee_recomm_id` parameter to an url string. For usage in widget template to construct item link URL.

type

### CreateRequestFunction

Factory for creating Recombee API Request to load data into a Widget.

type

### FetchContentOptions

CreateRequestFunction parameter

#### Properties

##### count

number

Number of items to fetch for the widget. Pass it to the appropriate Request constructor.

---