Recombee Docs
Visit recombee.comStart Free
docs20User Documentation
adminuiAdmin UI
reql32ReQL
codeAPI Clients & Integrations
cookhatScenario Recipes
suitcaseMisc
Table of contents
Widget SDKs / Carousel / Carousel Widget (JS)

Carousel Widget (JS)

A Vanilla JS 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 display a widget without using a transpiler like Babel and without using JSX. This library exports a htm HTML factory to assemble custom elements of the widget.

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

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

pnpm add @recombee/carousel-widget-js@0.1.12 recombee-js-api-client
Copy

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

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

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

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

export const  = new (, , {
  : ,
});
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.

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. See the Providing User ID section for details on how to obtain user ID in specific cases.

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

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

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:

TypeScriptJavaScript
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,
  });
};
Copy

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 + ESMJavaScript + ESMJavaScript + Browser
import {
  ,
  ,
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

({
  : "#widget-root",
  : ,
  : ,
  : "gap-4 p-6",
  : "min-w-[240px] min-h-[260px]",
  : () =>
    `<${}
      href=${(
        `${.?.?.link}`,
        ..,
      )}
      image=${`<${}
        src=${`${.?.?.images?.[0]}`}
        width=${600}
        height=${400}
      />`}
      labelContent=${`${.?.?.genres?.join(", ")}`}
      title=${`${.?.?.title}`}
      highlightedContent=${`${.?.?.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.

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 + ESMJavaScript + ESMJavaScript + Browser
import {
  ,
  ,
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

({
  : "#widget-root",
  : ,
  : ,
  :
    "overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white",
  : "gap-4 p-6",
  : "min-w-[240px] min-h-[260px]",
  : () =>
    `<${}
      classNameDisableBase
      className="border-b border-slate-600"
      contentWrapperClassName="text-center"
      href=${(
        `${.?.?.link}`,
        ..,
      )}
      image=${`<${}
        src=${`${.?.?.images?.[0]}`}
        width=${600}
        height=${400}
      />`}
      labelContent=${`${.?.?.genres?.join(", ")}`}
      title=${`${.?.?.title}`}
      highlightedContent=${`${.?.?.year}`}
    />`,
});
Copy

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 + ESMJavaScript + ESMJavaScript + Browser
import { , ,  } from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

({
  : "#widget-root",
  : ,
  : ,
  : "gap-4 p-6",
  : "min-h-[290px] w-[200px]",
  : () =>
    `<div
      className="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white"
    >
      <div className="relative overflow-hidden bg-cover bg-no-repeat">
        <${}
          src=${`${.?.?.images?.[0]}`}
          width=${600}
          height=${400}
        />${.?.?.["genres"]?.includes("drama") &&
        `<div
          className="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white"
        >
          Drama
        </div>`}${.?.?.["genres"]?.includes(
          "science_fiction",
        ) &&
        `<div
          className="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white"
        >
          Sci-Fi
        </div>`}
      </div>
      <div className="p-3">
        <div
          className="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]"
        >
          ${`${.?.?.genres?.join(", ")}`}
        </div>
        <div className="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
          ${`${.?.?.title}`}
        </div>
        <div className="line-clamp-4 pb-3 text-base text-[#3f91ff]">
          ${`${.?.?.year}`}
        </div>
        <button
          className="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]"
        >
          Play
        </button>
      </div>
    </div>`,
});
Copy

Custom Arrows

TypeScript + ESMJavaScript + ESMJavaScript + Browser
import {
  ,
  ,
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

({
  : "#widget-root",
  : ,
  : ,
  : "gap-4 p-6",
  : "min-h-[400px] w-[400px]",

  : () => {
    if (. === "left" && ...) {
      return `<button
        className="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]"
        type="button"
        onClick=${...}
      >
        prev
      </button>`;
    }

    if (. === "right" && ...) {
      return `<button
        className="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]"
        type="button"
        onClick=${...}
      >
        next
      </button>`;
    }
  },

  : () =>
    `<${}
      href=${(
        `${.?.?.link}`,
        ..,
      )}
      image=${`<${}
        src=${`${.?.?.images?.[0]}`}
        width=${600}
        height=${400}
      />`}
      labelContent=${`${.?.?.genres?.join(", ")}`}
      title=${`${.?.?.title}`}
      highlightedContent=${`${.?.?.year}`}
    />`,
});
Copy

Full Customization

TypeScript + ESMJavaScript + ESMJavaScript + Browser
import {
  ,
  ,
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

function (: any) {
  const  = `w-full rounded-lg border border-[#ededed] py-2 px-3 text-center text-[14px]/[1.43] font-medium text-[#80868f]`;

  return `<button
    className=${(, {
      "opacity-50": .disabled,
    })}
    ...${}
  />`;
}

({
  : "#widget-root",
  : ,
  : ,
  : () => null,
  : () =>
    `<div className="p-4"><${} ...${} contentClassName="gap-1" itemWrapperClassName="min-h-[240px] w-[200px]"/><div className="flex justify-end gap-2 pt-4"><div className="flex gap-2"><${} disabled=${!
      ...} onClick=${
      ...
    }>PREV</${}><${} disabled=${!.
      ..} onClick=${
      ...
    }>NEXT</${}></div></div></div>`,
  : () =>
    `<div
      className="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white"
    >
      <div className="relative overflow-hidden bg-cover bg-no-repeat">
        <${}
          src=${`${.?.?.images?.[0]}`}
          width=${600}
          height=${400}
        />${.?.?.["genres"]?.includes("drama") &&
        `<div
          className="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white"
        >
          Drama
        </div>`}${.?.?.["genres"]?.includes(
          "science_fiction",
        ) &&
        `<div
          className="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white"
        >
          Sci-Fi
        </div>`}
      </div>
      <div className="p-3">
        <div
          className="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]"
        >
          ${`${.?.?.genres?.join(", ")}`}
        </div>
        <div className="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
          ${`${.?.?.title}`}
        </div>
        <div className="line-clamp-4 pb-3 text-base text-[#3f91ff]">
          ${`${.?.?.year}`}
        </div>
        <button
          className="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]"
        >
          Play
        </button>
      </div>
    </div>`,
});
Copy

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 + ESMJavaScript + ESMJavaScript + Browser
import {
  ,
  ,
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

import "@recombee/carousel-widget-js/dist/styles.css";

({
  : "#widget-root",
  : ,
  : ,
  : true,
  :
    "rb:no-scrollbar flex min-h-[420px] snap-x snap-mandatory content-stretch gap-1 overflow-x-auto p-6",
  : true,
  :
    "min-h-[260px] flex min-w-full flex-grow basis-full snap-center",
  : () =>
    `<${}
      href=${(
        `${.?.?.link}`,
        ..,
      )}
      image=${`<${}
        src=${`${.?.?.images?.[0]}`}
        width=${600}
        height=${400}
      />`}
      labelContent=${`${.?.?.genres?.join(", ")}`}
      title=${`${.?.?.title}`}
      highlightedContent=${`${.?.?.year}`}
    />`,
});
Copy

API Reference

const

Carousel Widget initialization function

type

Carousel Widget configuration options.

Properties

string

CSS Selector to target the element where the widget should be inserted.

ApiClient

Instance of Recombee JS API Client. See Example.

CreateRequestFunction

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

WidgetRecommResponseCallback | undefined

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

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

({
  // ...ommited code...
  : ({ ,  }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  },
});
Copy
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.

number | undefined

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

string | undefined

Custom classes of widget wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of content wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of item wrapper element. See Custom CSS.

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.

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

A component rendering a single recommended item.

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

A component rendering either left or right carousel arrow

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

TypeScriptJavaScript
import React from "react";
import {
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

({
  // ...ommited code...
  : () => {
    return `
      <div>
        <h1>Recommended</h1>
        <${} ...${} />
      </div>
    `;
  },
});
Copy

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

TypeScriptJavaScript
import React from "react";
import { ,  } from "@recombee/carousel-widget-js";

({
  // ...ommited code...
  : () => {
    return `
      <div ref=${...}>
        <div ref=${...}>
          // Use carouselProps.state.items array to loop over items
        </div>
      </div>
    `;
  },
});
Copy
const

Default Item component provided for basic usage.

interface

Recommended item component properties.

Properties

string | undefined

Custom classes of item wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of item image wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of item content element. See Custom CSS.

Recommendation | undefined

A single item recommedation.

string | null | undefined

Item link URL.

ReactNode

Item Image element.

ReactNode

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

string | undefined

Custom classes of label content wrapper element. See Custom CSS.

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.

ReactNode

Item title.

string | undefined

Custom classes of title wrapper element. See Custom CSS.

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.

ReactNode

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

string | undefined

Custom classes of highlighted content wrapper element. See Custom CSS.

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.

ReactNode

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

const

Item image component

type

Item Image properties

Properties

string | null | undefined

Image URL

string | undefined

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

string | undefined

Image wrapper class name

string | undefined

Image class name

number | undefined

Image width in pixels

number | undefined

Image height in pixels

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

Image vertical alignment

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

Image horizontal alignment

"cover" | "scale_down" | undefined

Image fitting algorithm

function

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

type

Single recommendation item

Properties

string

Item ID

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

Item properties

type

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

type

CreateRequestFunction parameter

Properties

number

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

type

Carousel Widget React Component configuration properties

Properties

ApiClient

Instance of Recombee JS API Client. See Example.

CreateRequestFunction

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

WidgetRecommResponseCallback | undefined

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

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

({
  // ...ommited code...
  : ({ ,  }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  },
});
Copy
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.

number | undefined

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

string | undefined

Custom classes of widget wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of content wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of item wrapper element. See Custom CSS.

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.

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

A component rendering a single recommended item.

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

A component rendering either left or right carousel arrow

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

TypeScriptJavaScript
import React from "react";
import {
  ,
  ,
  ,
} from "@recombee/carousel-widget-js";

({
  // ...ommited code...
  : () => {
    return `
      <div>
        <h1>Recommended</h1>
        <${} ...${} />
      </div>
    `;
  },
});
Copy

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

TypeScriptJavaScript
import React from "react";
import { ,  } from "@recombee/carousel-widget-js";

({
  // ...ommited code...
  : () => {
    return `
      <div ref=${...}>
        <div ref=${...}>
          // Use carouselProps.state.items array to loop over items
        </div>
      </div>
    `;
  },
});
Copy
class

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

Properties

ObservableRef<HTMLElement>

React ref necessary to control the carousel wrapper element. See Customization Example.

ObservableRef<HTMLElement>

React ref necessary to control the carousel content element. See Customization Example.

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

Array of items to show in the carousel.

string | undefined

Id of recommendation response from which the items originated.

ArrowState

Current state of left Carousel arrow

ArrowState

Current state of right Carousel arrow

const

Default visual component used to render carousel container

interface

Carousel Properties

Properties

CarouselWidgetState

Carousel state.

string | undefined

Custom classes of widget wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of content wrapper element. See Custom CSS.

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.

string | undefined

Custom classes of item wrapper element. See Custom CSS.

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.

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

A component rendering a single recommended item.

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

A component rendering either left or right carousel arrow

const

Default Carousel arrow component

type

Carousel Arrow configuration options

Properties

"left" | "right"

The direction of an arrow to render.

CarouselWidgetState

Carousel state.

© Copyright 2025, Recombee s.r.o
docs.recombee.com