Widget SDKs / Carousel / Carousel Widget (React)

Carousel Widget (React)

A React component widget that displays a horizontal scroll of recommended items, designed to increase engagement through visually appealing item rotation.

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.0.5 and the API can change. Please specify exact version when installing.

Installation

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

pnpm add @recombee/carousel-widget-react@0.0.5 recombee-js-api-client

Copy

Client Initialization

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

TypeScript JavaScript

import { class ApiClientClient for sending requests to Recombee and getting repliesApiClient } from "recombee-js-api-client";

const const DATABASE_ID: "[database-id]"DATABASE_ID = "[database-id]";
const const PUBLIC_TOKEN: "[database-public-token]"PUBLIC_TOKEN = "[database-public-token]";
const const REGION: "[database-region]"REGION = "[database-region]";

export const const apiClient: ApiClientapiClient = new new ApiClient(databaseId: string, publicToken: string, options?: ApiClientOptions): ApiClient@paramdatabaseId - ID of your database.@parampublicToken - Corresponding public token.@paramoptions - Other custom options.ApiClient(const DATABASE_ID: "[database-id]"DATABASE_ID, const PUBLIC_TOKEN: "[database-public-token]"PUBLIC_TOKEN, {
  region?: string | undefinedregion: const REGION: "[database-region]"REGION,
});

Copy

The Database Public Token can be found in the Admin UI Database Settings Page.

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.

TypeScript JavaScript

import { type type CreateRequestFunction = (options: FetchContentOptions) => RequestFactory for creating Recombee API Request to load data into a Widget.
@publicCreateRequestFunction } from "@recombee/carousel-widget-react";
import { class RecommendItemsToUserBased on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.
The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.
The returned items are sorted by relevance (the first item being the most relevant).
Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
- Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
- Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.RecommendItemsToUser } from "recombee-js-api-client";

const const createRequest: CreateRequestFunctioncreateRequest: type CreateRequestFunction = (options: FetchContentOptions) => RequestFactory for creating Recombee API Request to load data into a Widget.
@publicCreateRequestFunction = ({ count: numberNumber of items to fetch for the widget. Pass it to the appropriate
Request constructor.count }) => {
  const const SCENARIO_ID: "recommend-items-to-user"SCENARIO_ID = "recommend-items-to-user";
  return new new RecommendItemsToUser(userId: string, count: number, optional?: {
    scenario?: string;
    cascadeCreate?: boolean;
    returnProperties?: boolean;
    includedProperties?: string[];
    filter?: string;
    booster?: string;
    logic?: string | object;
    diversity?: number;
    minRelevance?: string;
    rotationRate?: number;
    rotationTime?: number;
    expertSettings?: {
        [key: string]: unknown;
    };
    returnAbGroup?: boolean;
}): RecommendItemsToUser@paramuserId - ID of the user for whom personalized recommendations are to be generated.@paramcount - Number of items to be recommended (N for the top-N recommendation).@paramoptional - Optional parameters given as an object.RecommendItemsToUser(userId, count: numberNumber of items to fetch for the widget. Pass it to the appropriate
Request constructor.count, {
    scenario?: string | undefinedScenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".scenario: const SCENARIO_ID: "recommend-items-to-user"SCENARIO_ID,
    cascadeCreate?: boolean | undefinedIf the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.cascadeCreate: true,
    returnProperties?: boolean | undefinedWith `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.returnProperties: true,
  });
};

Copy

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 ID - depending on the specific type of recommendation request.

Basic Example

The widget in this example uses the 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 is set in the request, and optionally use includedProperties to control which item properties are returned.

TypeScript + ESM JavaScript + ESM

import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => {
  return (
    <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
      WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
      WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
      type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
        <const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem
          DefaultItemProps.href?: string | null | undefinedItem link URL.
@publichref={function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
            `${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
            props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.state: CarouselWidgetStatestate.CarouselWidgetState.recommId: string | undefinedId of recommendation response from which the items originated.
@publicrecommId,
          )}
          DefaultItemProps.image?: React.ReactNodeItem Image element.
@publicimage={
            <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
              src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
              width?: number | undefinedImage width in pixels
@publicwidth={600}
              height?: number | undefinedImage height in pixels
@publicheight={400}
            />
          }
          DefaultItemProps.labelContent?: React.ReactNodeItem content above title. Sets the entire content of an item aside from
an image.
@publiclabelContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
          DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
          DefaultItemProps.highlightedContent?: React.ReactNodeItem content under title. Sets the entire content of an item aside from
an image.
@publichighlightedContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
        />
      )}
    />
  );
};

Copy

The addRecommIdQueryParam utility function is used to append the recommendation ID to the item's URL as the recombee_recomm_id query parameter.

This enables you to report successful (clicked) recommendations back to Recombee for improved tracking and performance optimization.

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 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>
  <ArrowComponent arrowDirection="left" />
  <ArrowComponent arrowDirection="right" />
</div>

Copy

This is handy to understand how to customize the widget to full potential.

Setting own classes

TypeScript + ESM JavaScript + ESM

import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => {
  return (
    <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
      WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
      WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
      className?: string | undefinedCustom classes of widget wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicclassName="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white"
      type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
        <const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem
          DefaultItemProps.classNameDisableBase?: boolean | undefinedDisables 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 
{@link 
file://./#custom-css Custom CSS
}
.
@publicclassNameDisableBase
          DefaultItemProps.className?: string | undefinedCustom classes of item wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicclassName="border-b border-slate-600"
          DefaultItemProps.contentWrapperClassName?: string | undefinedCustom classes of item content element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentWrapperClassName="text-center"
          DefaultItemProps.href?: string | null | undefinedItem link URL.
@publichref={function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
            `${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
            props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.state: CarouselWidgetStatestate.CarouselWidgetState.recommId: string | undefinedId of recommendation response from which the items originated.
@publicrecommId,
          )}
          DefaultItemProps.image?: React.ReactNodeItem Image element.
@publicimage={
            <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
              src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
              width?: number | undefinedImage width in pixels
@publicwidth={600}
              height?: number | undefinedImage height in pixels
@publicheight={400}
            />
          }
          DefaultItemProps.labelContent?: React.ReactNodeItem content above title. Sets the entire content of an item aside from
an image.
@publiclabelContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
          DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
          DefaultItemProps.highlightedContent?: React.ReactNodeItem content under title. Sets the entire content of an item aside from
an image.
@publichighlightedContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
        />
      )}
    />
  );
};

Copy

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

TypeScript + ESM JavaScript + ESM

import { const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget, const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage } from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => {
  return (
    <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
      WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
      WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
      itemWrapperClassName?: string | undefinedCustom classes of item wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicitemWrapperClassName="min-h-[240px] w-[200px]"
      type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
        <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white">
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="relative overflow-hidden bg-cover bg-no-repeat">
            <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
              src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
              width?: number | undefinedImage width in pixels
@publicwidth={600}
              height?: number | undefinedImage height in pixels
@publicheight={400}
            />
            {props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.["genres"]?.includes("drama") && (
              <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white">
                Drama
              </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
            )}
            {props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.["genres"]?.includes("science_fiction") && (
              <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white">
                Sci-Fi
              </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
            )}
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="p-3">
            <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]">
              {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
            </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
            <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
              {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
            </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
            <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="line-clamp-4 pb-3 text-base text-[#3f91ff]">
              {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
            </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
            <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button React.HTMLAttributes<T>.className?: string | undefinedclassName="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]">
              Play
            </React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
        </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
      )}
    />
  );
};

Copy

Custom Arrows

TypeScript + ESM JavaScript + ESM

import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => {
  return (
    <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
      WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
      WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
      itemWrapperClassName?: string | undefinedCustom classes of item wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicitemWrapperClassName="min-h-[400px] w-[400px]"
      ArrowComponent?: ((props: CarouselArrowProps) => React.ReactNode) | undefinedA component rendering either left or right carousel arrow
@publicArrowComponent={(props: CarouselArrowPropsprops) => {
        if (
          props: CarouselArrowPropsprops.arrowDirection: "left" | "right"The direction of an arrow to render.
@publicarrowDirection === "left" &&
          props: CarouselArrowPropsprops.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.leftArrow: ArrowStateCurrent state of left Carousel arrow
@publicleftArrow.isVisible: booleanisVisible
        ) {
          return (
            <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button
              React.HTMLAttributes<HTMLButtonElement>.className?: string | undefinedclassName="absolute top-1/2 left-4 -translate-y-6 rounded-lg rounded-sm border border-[#ededed] bg-white px-3 py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]"
              React.ButtonHTMLAttributes<HTMLButtonElement>.type?: "button" | "submit" | "reset" | undefinedtype="button"
              React.DOMAttributes<HTMLButtonElement>.onClick?: React.MouseEventHandler<HTMLButtonElement> | undefinedonClick={props: CarouselArrowPropsprops.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.leftArrow: ArrowStateCurrent state of left Carousel arrow
@publicleftArrow.handleClick: () => voidhandleClick}
            >
              prev
            </React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>
          );
        }
        if (
          props: CarouselArrowPropsprops.arrowDirection: "left" | "right"The direction of an arrow to render.
@publicarrowDirection === "right" &&
          props: CarouselArrowPropsprops.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.rightArrow: ArrowStateCurrent state of right Carousel arrow
@publicrightArrow.isVisible: booleanisVisible
        ) {
          return (
            <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button
              React.HTMLAttributes<HTMLButtonElement>.className?: string | undefinedclassName="absolute top-1/2 right-4 -translate-y-6 rounded-lg rounded-sm border border-[#ededed] bg-white px-3 py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]"
              React.ButtonHTMLAttributes<HTMLButtonElement>.type?: "button" | "submit" | "reset" | undefinedtype="button"
              React.DOMAttributes<HTMLButtonElement>.onClick?: React.MouseEventHandler<HTMLButtonElement> | undefinedonClick={props: CarouselArrowPropsprops.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.rightArrow: ArrowStateCurrent state of right Carousel arrow
@publicrightArrow.handleClick: () => voidhandleClick}
            >
              next
            </React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>
          );
        }
      }}
      type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
        <const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem
          DefaultItemProps.href?: string | null | undefinedItem link URL.
@publichref={function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
            `${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
            props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.state: CarouselWidgetStatestate.CarouselWidgetState.recommId: string | undefinedId of recommendation response from which the items originated.
@publicrecommId,
          )}
          DefaultItemProps.image?: React.ReactNodeItem Image element.
@publicimage={
            <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
              src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
              width?: number | undefinedImage width in pixels
@publicwidth={600}
              height?: number | undefinedImage height in pixels
@publicheight={400}
            />
          }
          DefaultItemProps.labelContent?: React.ReactNodeItem content above title. Sets the entire content of an item aside from
an image.
@publiclabelContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
          DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
          DefaultItemProps.highlightedContent?: React.ReactNodeItem content under title. Sets the entire content of an item aside from
an image.
@publichighlightedContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
        />
      )}
    />
  );
};

Copy

Full Customization

TypeScript + ESM JavaScript + ESM

import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultCarousel: ((props: DefaultCarouselProps) => React.JSX.Element) & {
    displayName: string;
}Default visual component used to render carousel container
@publicDefaultCarousel,
  const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage,
  function clsx(...inputs: ClassValue[]): stringclsx,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => (
  <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
    WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
    WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
    ArrowComponent?: ((props: CarouselArrowProps) => React.ReactNode) | undefinedA component rendering either left or right carousel arrow
@publicArrowComponent={() => null}
    CarouselComponent?: ((props: DefaultCarouselProps) => React.ReactNode) | undefinedComponent responsible for rendering the widget markup.

Example in which the passed component wraps the default carousel
component with additional custom HTML.

```tsx|-react
import React from "react";
import {
  CarouselWidget,
  DefaultCarousel,
} from "@recombee/carousel-widget-react";

//
@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div>
<h1>Recommended</h1>
<DefaultCarousel {...carouselProps} />
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import {
CarouselWidget,
DefaultCarousel,
html,
} from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div>
<h1>Recommended</h1>
<${DefaultCarousel} ...${carouselProps} />
</div>
`;
},
});
```

This property also allows to fully cutomize the carousel HTML in extreme
cases.

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

//@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div ref={carouselProps.state.wrapperRef.handle}>
<h1>Recommended</h1>
<div ref={carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget, html } from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div ref=${carouselProps.state.wrapperRef.handle}>
<div ref=${carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
`;
},
});
```@publicCarouselComponent={(props: DefaultCarouselProps<React.ReactNode>props) => (
      <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="p-4">
        <const DefaultCarousel: ((props: DefaultCarouselProps) => React.JSX.Element) & {
    displayName: string;
}Default visual component used to render carousel container
@publicDefaultCarousel
          {...props: DefaultCarouselProps<React.ReactNode>props}
          DefaultCarouselProps<React.ReactNode>.contentClassName?: string | undefinedCustom classes of content wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentClassName="gap-1"
          DefaultCarouselProps<React.ReactNode>.itemWrapperClassName?: string | undefinedCustom classes of item wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicitemWrapperClassName="min-h-[240px] w-[200px]"
        />
        <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="flex justify-end gap-2 pt-4">
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="flex gap-2">
            <function CarouselButton(props: any): React.JSX.ElementCarouselButton
              disabled: booleandisabled={!props: DefaultCarouselProps<React.ReactNode>props.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.leftArrow: ArrowStateCurrent state of left Carousel arrow
@publicleftArrow.isVisible: booleanisVisible}
              onClick: () => voidonClick={props: DefaultCarouselProps<React.ReactNode>props.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.leftArrow: ArrowStateCurrent state of left Carousel arrow
@publicleftArrow.handleClick: () => voidhandleClick}
            >
              PREV
            </function CarouselButton(props: any): React.JSX.ElementCarouselButton>
            <function CarouselButton(props: any): React.JSX.ElementCarouselButton
              disabled: booleandisabled={!props: DefaultCarouselProps<React.ReactNode>props.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.rightArrow: ArrowStateCurrent state of right Carousel arrow
@publicrightArrow.isVisible: booleanisVisible}
              onClick: () => voidonClick={props: DefaultCarouselProps<React.ReactNode>props.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.rightArrow: ArrowStateCurrent state of right Carousel arrow
@publicrightArrow.handleClick: () => voidhandleClick}
            >
              NEXT
            </function CarouselButton(props: any): React.JSX.ElementCarouselButton>
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
        </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
      </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
    )}
    type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
      <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white">
        <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="relative overflow-hidden bg-cover bg-no-repeat">
          <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
            src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
            width?: number | undefinedImage width in pixels
@publicwidth={600}
            height?: number | undefinedImage height in pixels
@publicheight={400}
          />
          {props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.["genres"]?.includes("drama") && (
            <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white">
              Drama
            </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          )}
          {props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.["genres"]?.includes("science_fiction") && (
            <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white">
              Sci-Fi
            </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          )}
        </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
        <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="p-3">
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]">
            {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
            {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="line-clamp-4 pb-3 text-base text-[#3f91ff]">
            {`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
          </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
          <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button React.HTMLAttributes<T>.className?: string | undefinedclassName="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]">
            Play
          </React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>
        </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
      </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
    )}
  />
);

function function CarouselButton(props: any): React.JSX.ElementCarouselButton(props: anyprops: any) {
  const const buttonClassName: "w-full rounded-lg border border-[#ededed] py-2 px-3 text-center text-[14px]/[1.43] font-medium text-[#80868f]"buttonClassName = `w-full rounded-lg border border-[#ededed] py-2 px-3 text-center text-[14px]/[1.43] font-medium text-[#80868f]`;

  return (
    <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button
      React.HTMLAttributes<T>.className?: string | undefinedclassName={function clsx(...inputs: ClassValue[]): stringclsx(const buttonClassName: "w-full rounded-lg border border-[#ededed] py-2 px-3 text-center text-[14px]/[1.43] font-medium text-[#80868f]"buttonClassName, {
        "opacity-50": props: anyprops.disabled,
      })}
      {...props: anyprops}
    />
  );
}

Copy

Overriding Base Classes

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

However, these can be disabled or overridden if needed. Use the CarouselWidgetProps.classNameDisableDefault and related options to opt out of default styling.

TypeScript + ESM JavaScript + ESM

import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";

export default () => {
  return (
    <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="flex justify-center">
      <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.HTMLAttributes<HTMLDivElement>.className?: string | undefinedclassName="w-[40%]">
        <const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
          WidgetConfigurationBase<CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient={const apiClient: ApiClientapiClient}
          WidgetConfigurationBase<CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest={const createRequest: CreateRequestFunctioncreateRequest}
          contentClassNameDisableDefault?: boolean | undefinedDisables 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 
{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentClassNameDisableDefault
          contentClassName?: string | undefinedCustom classes of content wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentClassName="rb:no-scrollbar flex min-h-[420px] snap-x snap-mandatory content-stretch gap-1 overflow-x-auto p-6"
          itemWrapperClassNameDisableDefault?: boolean | undefinedDisables 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 
{@link 
file://./#custom-css Custom CSS
}
.
@publicitemWrapperClassNameDisableDefault
          itemWrapperClassName?: string | undefinedCustom classes of item wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicitemWrapperClassName="flex min-w-full flex-grow basis-full snap-center"
          type ItemComponent: (props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}) => React.ReactNodeA component rendering a single recommended item.
@publicItemComponent={(props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props) => (
            <const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem
              DefaultItemProps.href?: string | null | undefinedItem link URL.
@publichref={function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
                `${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
                props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.state: CarouselWidgetStatestate.CarouselWidgetState.recommId: string | undefinedId of recommendation response from which the items originated.
@publicrecommId,
              )}
              DefaultItemProps.image?: React.ReactNodeItem Image element.
@publicimage={
                <const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage
                  src?: string | null | undefinedImage URL
@publicsrc={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.images?.[0]}`}
                  width?: number | undefinedImage width in pixels
@publicwidth={600}
                  height?: number | undefinedImage height in pixels
@publicheight={400}
                />
              }
              DefaultItemProps.labelContent?: React.ReactNodeItem content above title. Sets the entire content of an item aside from
an image.
@publiclabelContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
              DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.title}`}
              DefaultItemProps.highlightedContent?: React.ReactNodeItem content under title. Sets the entire content of an item aside from
an image.
@publichighlightedContent={`${props: {
    state: CarouselWidgetState;
    result?: Recommendation;
}props.result?: Recommendation | undefinedresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
            />
          )}
        />
      </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
    </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
  );
};

Copy

API Reference

const

CarouselWidget

Carousel widget React Component. See CarouselWidgetProps for configuration options.

type

CarouselWidgetProps

Carousel Widget React Component configuration properties

Properties

apiClient

ApiClient

Instance of Recombee JS API Client. See Example.

createRequest

CreateRequestFunction

Request factory function. See Quick Example or visit API Reference for overview of available requests.

onRecommResponse

WidgetRecommResponseCallback | undefined

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

TypeScript JavaScript

import React from "react";
import { const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget } from "@recombee/carousel-widget-react";

<const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
  // ...ommited code...
  WidgetConfigurationBase<CreateRequestFunction>.onRecommResponse?: WidgetRecommResponseCallback | undefinedCallback function allowing to intercept and inspect recommendation
request+response made by widget.

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

//
@noErrors: 2739 2345
<CarouselWidget
// ...ommited code...
onRecommResponse={({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget } from "@recombee/carousel-widget-js";

//@noErrors: 2739 2345
CarouselWidget({
// ...ommited code...
onRecommResponse: ({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
},
});
```@publiconRecommResponse={({ recombeeRequest: RequestrecombeeRequest, recombeeResponse: anyrecombeeResponse }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  }}
/>;

Copy

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.

initialItemsCount

number | undefined

Number of items to load immediately. Adjust to have more items loaded ahead of user scrolling.

className

string | undefined

Custom classes of widget wrapper element. See 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.

contentClassName

string | undefined

Custom classes of content wrapper element. See Custom CSS.

contentClassNameDisableDefault

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

itemWrapperClassName

string | undefined

Custom classes of item wrapper element. See 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.

ItemComponent

(props: { state: CarouselWidgetState; result?: Recommendation | undefined; }) => ReactNode

A component rendering a single recommended item.

ArrowComponent

((props: CarouselArrowProps) => ReactNode) | undefined

A component rendering either left or right carousel arrow

CarouselComponent

((props: DefaultCarouselProps<ReactNode>) => ReactNode) | undefined

Component responsible for rendering the widget markup.

Example in which the passed component wraps the default carousel component with additional custom HTML.

TypeScript JavaScript

import React from "react";
import {
  const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget,
  const DefaultCarousel: ((props: DefaultCarouselProps) => React.JSX.Element) & {
    displayName: string;
}Default visual component used to render carousel container
@publicDefaultCarousel,
} from "@recombee/carousel-widget-react";

<const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
  // ...ommited code...
  CarouselComponent?: ((props: DefaultCarouselProps) => React.ReactNode) | undefinedComponent responsible for rendering the widget markup.

Example in which the passed component wraps the default carousel
component with additional custom HTML.

```tsx|-react
import React from "react";
import {
  CarouselWidget,
  DefaultCarousel,
} from "@recombee/carousel-widget-react";

//
@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div>
<h1>Recommended</h1>
<DefaultCarousel {...carouselProps} />
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import {
CarouselWidget,
DefaultCarousel,
html,
} from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div>
<h1>Recommended</h1>
<${DefaultCarousel} ...${carouselProps} />
</div>
`;
},
});
```

This property also allows to fully cutomize the carousel HTML in extreme
cases.

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

//@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div ref={carouselProps.state.wrapperRef.handle}>
<h1>Recommended</h1>
<div ref={carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget, html } from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div ref=${carouselProps.state.wrapperRef.handle}>
<div ref=${carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
`;
},
});
```@publicCarouselComponent={(carouselProps: DefaultCarouselProps<React.ReactNode>carouselProps) => {
    return (
      <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
        <React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>Recommended</React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>
        <const DefaultCarousel: ((props: DefaultCarouselProps) => React.JSX.Element) & {
    displayName: string;
}Default visual component used to render carousel container
@publicDefaultCarousel {...carouselProps: DefaultCarouselProps<React.ReactNode>carouselProps} />
      </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
    );
  }}
/>;

Copy

This property also allows to fully cutomize the carousel HTML in extreme cases.

TypeScript JavaScript

import React from "react";
import { const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget } from "@recombee/carousel-widget-react";

<const CarouselWidget: React.FunctionComponent<CarouselWidgetProps>Carousel widget React Component. See 
{@link 
CarouselWidgetProps
}
 for
configuration options.
@publicCarouselWidget
  // ...ommited code...
  CarouselComponent?: ((props: DefaultCarouselProps) => React.ReactNode) | undefinedComponent responsible for rendering the widget markup.

Example in which the passed component wraps the default carousel
component with additional custom HTML.

```tsx|-react
import React from "react";
import {
  CarouselWidget,
  DefaultCarousel,
} from "@recombee/carousel-widget-react";

//
@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div>
<h1>Recommended</h1>
<DefaultCarousel {...carouselProps} />
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import {
CarouselWidget,
DefaultCarousel,
html,
} from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div>
<h1>Recommended</h1>
<${DefaultCarousel} ...${carouselProps} />
</div>
`;
},
});
```

This property also allows to fully cutomize the carousel HTML in extreme
cases.

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

//@noErrors: 2739
<CarouselWidget
// ...ommited code...
CarouselComponent={(carouselProps) => {
return (
<div ref={carouselProps.state.wrapperRef.handle}>
<h1>Recommended</h1>
<div ref={carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
);
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget, html } from "@recombee/carousel-widget-js";

//@noErrors: 2345
CarouselWidget({
// ...ommited code...
CarouselComponent: (carouselProps) => {
return html`
<div ref=${carouselProps.state.wrapperRef.handle}>
<div ref=${carouselProps.state.contentRef.handle}>
// Use carouselProps.state.items array to loop over items
</div>
</div>
`;
},
});
```@publicCarouselComponent={(carouselProps: DefaultCarouselProps<React.ReactNode>carouselProps) => {
    return (
      <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.RefAttributes<HTMLDivElement>.ref?: React.Ref<HTMLDivElement> | undefinedAllows getting a ref to the component instance.
Once the component unmounts, React will set `ref.current` to `null`
(or call the ref with `null` if you passed a callback ref).
@see{@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}ref={carouselProps: DefaultCarouselProps<React.ReactNode>carouselProps.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.wrapperRef: ObservableRef<HTMLElement>React ref necessary to control the carousel wrapper element. See

{@link 
CarouselWidgetProps.CarouselComponent
Customization Example
}
.wrapperRef.ObservableRef<HTMLElement>.handle(element: HTMLElement | null): voidhandle}>
        <React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>Recommended</React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>
        <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div React.RefAttributes<HTMLDivElement>.ref?: React.Ref<HTMLDivElement> | undefinedAllows getting a ref to the component instance.
Once the component unmounts, React will set `ref.current` to `null`
(or call the ref with `null` if you passed a callback ref).
@see{@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}ref={carouselProps: DefaultCarouselProps<React.ReactNode>carouselProps.DefaultCarouselProps<React.ReactNode>.state: CarouselWidgetStateCarousel state.
@publicstate.CarouselWidgetState.contentRef: ObservableRef<HTMLElement>React ref necessary to control the carousel content element. See

{@link 
CarouselWidgetProps.CarouselComponent
Customization Example
}
.contentRef.ObservableRef<HTMLElement>.handle(element: HTMLElement | null): voidhandle}>
          // Use carouselProps.state.items array to loop over items
        </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
      </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
    );
  }}
/>;

Copy

class

CarouselWidgetState

Exposes internal state data of the widget to be used in customizable components

Properties

wrapperRef

ObservableRef<HTMLElement>

React ref necessary to control the carousel wrapper element. See CarouselWidgetProps.CarouselComponent.

contentRef

ObservableRef<HTMLElement>

React ref necessary to control the carousel content element. See CarouselWidgetProps.CarouselComponent.

items

{ key: string; entity: Recommendation; }[]

Array of items to show in the carousel.

recommId

string | undefined

Id of recommendation response from which the items originated.

leftArrow

ArrowState

Current state of left Carousel arrow

rightArrow

ArrowState

Current state of right Carousel arrow

const

DefaultItem

Default Item component provided for basic usage.

interface

DefaultItemProps

Properties

className

string | undefined

Custom classes of item wrapper element. See 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.

imageWrapperClassName

string | undefined

Custom classes of item image wrapper element. See 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.

contentWrapperClassName

string | undefined

Custom classes of item content element. See 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.

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.

title

ReactNode

Item title.

titleWrapperClassName

string | undefined

Custom classes of title wrapper element. See 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.

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.

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.

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.

const

DefaultCarousel

Default visual component used to render carousel container

interface

DefaultCarouselProps

Carousel Properties

Properties

state

CarouselWidgetState

Carousel state.

className

string | undefined

Custom classes of widget wrapper element. See 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.

contentClassName

string | undefined

Custom classes of content wrapper element. See Custom CSS.

contentClassNameDisableDefault

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

itemWrapperClassName

string | undefined

Custom classes of item wrapper element. See 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.

ItemComponent

(props: { state: CarouselWidgetState; result?: Recommendation | undefined; }) => ElementType

A component rendering a single recommended item.

ArrowComponent

((props: CarouselArrowProps) => ElementType) | undefined

A component rendering either left or right carousel arrow

const

DefaultCarouselArrow

Default Carousel arrow component

type

CarouselArrowProps

Carousel Arrow configuration options

Properties

arrowDirection

"left" | "right"

The direction of an arrow to render.

state

CarouselWidgetState

Carousel state.

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.