# Carousel Widget (JS) > Source: https://docs.recombee.com/widget-sdks/carousel-widget-js > For the complete documentation index, see [llms.txt](/llms.txt). **Table of contents** * [ Installation ](#install) * [ Client Initialization ](#client-initialization) * [ Providing User ID ](#providing-user-id) * [ Basic Example ](#basic-example) * [ Custom CSS ](#custom-css) * [ Custom Templates ](#custom-templates) * [ Overriding Base Classes ](#overriding-base-classes) * [ Composite Recommendations ](#composite-recommendations) * [API Reference](#api) * [CarouselWidget](#api/CarouselWidget) * [CarouselWidgetOptions](#api/CarouselWidgetOptions) * [DefaultItem](#api/DefaultItem) * [DefaultItemProps](#api/DefaultItemProps) * [ItemImage](#api/ItemImage) * [ItemImageProps](#api/ItemImageProps) * [addRecommIdQueryParam](#api/addRecommIdQueryParam) * [Recommendation](#api/Recommendation) * [CreateRequestFunction](#api/CreateRequestFunction) * [FetchContentOptions](#api/FetchContentOptions) * [CarouselWidgetProps](#api/CarouselWidgetProps) * [CarouselWidgetState](#api/CarouselWidgetState) * [DefaultCarousel](#api/DefaultCarousel) * [DefaultCarouselProps](#api/DefaultCarouselProps) * [DefaultCarouselArrow](#api/DefaultCarouselArrow) * [CarouselArrowProps](#api/CarouselArrowProps) # 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.2.19 and the API can change. Please specify exact version when installing. ## Installation Install `@recombee/carousel-widget-js@0.2.19` and `recombee-js-api-client`packages using your preferred NPM package manager. This example is using`pnpm`. ``` pnpm add @recombee/carousel-widget-js@0.2.19 recombee-js-api-client ``` Always remember to apply the default CSS file distributed alongside the widget library, as shown in the examples. ## Client Initialization The widget loads recommendation data using [Recombee API Client](/js_client). Here is how to initialize the client with necessary configuration for a specific database: ``` import { } from "recombee-js-api-client"; const = "[database-id]"; const = "[database-public-token]"; const = "[database-region]"; export const = new (, , { : , }); ``` The Database Public Token can be found in the Admin UI[Database Settings Page](https://admin.recombee.com/go-to-database/settings). The widget also needs to be provided a `createRequest` function, which instantiates a client request class to define which data to pull from the database. Use Scenario ID which can be found on Admin GUI[Database Scenarios Page](https://admin.recombee.com/go-to-database/scenarios). Please ensure that you provide the user ID (typically obtained from your existing user tracking system), along with other relevant parameters - such as an item ID or [Item Segment](/segmentations) ID - depending on the specific type of recommendation request. See the[Providing User ID](#providing-user-id) section for details on how to obtain user ID in specific cases. ``` import { type } from "@recombee/carousel-widget-react"; import { } from "recombee-js-api-client"; const : = ({ }) => { const = "recommend-items-to-user"; return new (userId, , { : , : true, : true, }); }; ``` ### Providing User ID Each visitor of your website should be identified by a user identificator (`userId`) to correlate user activity and deliver best possible recommendation performance. The `userId` should preferrably originate from your user's account details when the user is authenticated or as some session-persistent random ID when they are anonymous. The SDK provides utility which generates random user id and saves it to a cookie to cover the latter case: ``` import { type } from "@recombee/carousel-widget-react"; import { } from "recombee-js-api-client"; import { } from "@recombee/carousel-widget-react"; let : string | undefined; if (authenticatedUserId) { = authenticatedUserId; } else { = .(); } const : = ({ }) => { const = "recommend-items-to-user"; return new (, , { : , : true, : true, }); }; ``` ## Basic Example The widget in this example uses the [DefaultItem](#api/DefaultItem) component to render each recommendation in a consistent layout. The resulting widget is inserted into the element specified by the`container` field. Values of the recommended items - such as title, image URL, or link URL - are obtained from the API response and accessed via `props.result?.values`. Ensure that [returnProperties: true](/api#recommend-items-to-user-param-returnProperties) is set in the request, and optionally use[includedProperties](/api#recommend-items-to-user-param-includedProperties)to control which item properties are returned. ``` import { , , , , , } from "@recombee/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}`} />`, }); ``` The [addRecommIdQueryParam](#api/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](/admin_ui#reported-metrics) 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](https://tailwindcss.com/) for styling. Class names for internal elements and custom components are passed as props and applied by the widget during rendering. The default structure of the_Basic Example_ widget is illustrated below (pseudo-code): ```
... more items ...
``` This is handy to understand how to customize the widget to full potential. ### Setting own classes ``` 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}`} />`, }); ``` ## Custom Templates Recombee Widgets support full customization of internal components such as the appearance of the recommended items. You can provide your own components via props like [ItemComponent](#api/ItemComponent) to control the structure, styling, and behavior of the widget. This flexibility allows you to adapt the widget's appearance and functionality to match your design and user experience requirements. ### Custom Item ``` import { , , } from "@recombee/carousel-widget-js"; import "@recombee/carousel-widget-js/dist/styles.css"; ({ : "#widget-root", : , : , : "gap-4 p-6", : "min-h-[290px] w-[200px]", : () => `
<${} src=${`${.?.?.images?.[0]}`} width=${600} height=${400} />${.?.?.["genres"]?.includes("drama") && `
Drama
`}${.?.?.["genres"]?.includes( "science_fiction", ) && `
Sci-Fi
`}
${`${.?.?.genres?.join(", ")}`}
${`${.?.?.title}`}
${`${.?.?.year}`}
`, }); ``` ### Custom Arrows ``` 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 ``; } if (. === "right" && ...) { return ``; } }, : () => `<${} href=${( .?.?.link, .., )} image=${`<${} src=${`${.?.?.images?.[0]}`} width=${600} height=${400} />`} labelContent=${`${.?.?.genres?.join(", ")}`} title=${`${.?.?.title}`} highlightedContent=${`${.?.?.year}`} />`, }); ``` ### Full Customization ``` 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 ` `, }); ``` ## 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](#api/CarouselWidgetProps.classNameDisableDefault) and related options to opt out of default styling. ``` 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}`} />`, }); ``` ## Composite Recommendations ``` const : = ({ }) => { return new ("top-from-genre-for-you", , { : { : true, }, }); }; 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]", : ({ }) => { return ? `

Because you like ${?.}

` : null; }, : () => `<${} href=${( .?.?.link, .., )} image=${`<${} src=${`${.?.?.images?.[0]}`} width=${600} height=${400} />`} labelContent=${`${.?.?.genres?.join(", ")}`} title=${`${.?.?.title}`} highlightedContent=${`${.?.?.year}`} />`, }); ``` ## API Reference const ### CarouselWidget Carousel Widget initialization function type ### CarouselWidgetOptions Carousel Widget configuration options. #### Properties ##### container string CSS Selector to target the element where the widget should be inserted. --- ##### apiClient ApiClient Instance of Recombee JS API Client. See[Example](#client-initialization). --- ##### createRequest CreateRequestFunction Request factory function. See[Quick Example](#client-initialization) or visit[API Reference](/api) for overview of available requests. --- ##### onRecommResponse WidgetRecommResponseCallback | undefined Callback function allowing to intercept and inspect recommendation request+response made by widget. ``` import React from "react"; import { } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : ({ , }) => { // use data from request and response for any purpose, i.e. internal tracking }, }); ``` --- ##### deduplicationPartitionKey string | undefined A string key specifying a group of widgets, in which recommendation results will be deduplicated. By default, all widgets belong to a single group so all results from the same database are deduplicated. --- ##### 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](#custom-css). --- ##### classNameDisableDefault boolean | undefined Disables default classes of widget wrapper element. There are some default class names with essential styles applied to the widget wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### contentClassName string | undefined Custom classes of content wrapper element. See[Custom CSS](#custom-css). --- ##### contentClassNameDisableDefault boolean | undefined Disables default classes of content wrapper element. There are some default class names with essential styles applied to the content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### itemWrapperClassName string | undefined Custom classes of item wrapper element. See[Custom CSS](#custom-css). --- ##### itemWrapperClassNameDisableDefault boolean | undefined Disables default classes of item wrapper element. There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### SourceItemComponent ((props: { state: CarouselWidgetState; source?: Recommendation | null | undefined; }) => ReactNode) | undefined A component rendering a source recommended item when using Composite Scenario. --- ##### 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) | undefined Component responsible for rendering the widget markup. Example in which the passed component wraps the default carousel component with additional custom HTML. ``` import React from "react"; import { , , , } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : () => { return `

Recommended

<${} ...${} />
`; }, }); ``` This property also allows to fully cutomize the carousel HTML in extreme cases. ``` import React from "react"; import { , } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : () => { return `
// Use carouselProps.state.items array to loop over items
`; }, }); ``` --- const ### DefaultItem Default Item component provided for basic usage. interface ### DefaultItemProps Recommended item component properties. #### Properties ##### className string | undefined Custom classes of item wrapper element. See[Custom CSS](#custom-css). --- ##### classNameDisableBase boolean | undefined Disables default classes of item wrapper element. There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### imageWrapperClassName string | undefined Custom classes of item image wrapper element. See[Custom CSS](#custom-css). --- ##### imageWrapperClassNameDisableBase boolean | undefined Disables default classes of item image wrapper element. There are some default class names with essential styles applied to the item image wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### contentWrapperClassName string | undefined Custom classes of item content element. See[Custom CSS](#custom-css). --- ##### result Recommendation | undefined A single item recommedation. --- ##### href string | null | undefined Item link URL. --- ##### image ReactNode Item Image element. --- ##### labelContent ReactNode Item content above title. Sets the entire content of an item aside from an image. --- ##### labelContentWrapperClassName string | undefined Custom classes of label content wrapper element. See[Custom CSS](#custom-css). --- ##### labelContentWrapperClassNameDisableBase boolean | undefined Disables default classes of label content wrapper element. There are some default class names with essential styles applied to the label content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### title ReactNode Item title. --- ##### titleWrapperClassName string | undefined Custom classes of title wrapper element. See[Custom CSS](#custom-css). --- ##### titleWrapperClassNameDisableBase boolean | undefined Disables default classes of title wrapper element. There are some default class names with essential styles applied to the title wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### highlightedContent ReactNode Item content under title. Sets the entire content of an item aside from an image. --- ##### highlightedContentWrapperClassName string | undefined Custom classes of highlighted content wrapper element. See[Custom CSS](#custom-css). --- ##### highlightedContentWrapperClassNameDisableBase boolean | undefined Disables default classes of highlighted content wrapper element. There are some default class names with essential styles applied to the highlighted content wrapper element. This setting disables them as an escape hatch for customization. See[Custom CSS](#custom-css). --- ##### bottomContent ReactNode Any custom content to display at the bottom of the item. --- const ### ItemImage Item image component type ### ItemImageProps Item Image properties #### Properties ##### src string | null | undefined Image URL --- ##### missingImageSrc string | undefined URL of an image to display when the main image could not be loaded. --- ##### className string | undefined Image wrapper class name --- ##### imgClassName string | undefined Image class name --- ##### width number | undefined Image width in pixels --- ##### height number | undefined Image height in pixels --- ##### verticalAlignment "top" | "center" | "bottom" | undefined Image vertical alignment --- ##### horizontalAlignment "center" | "left" | "right" | undefined Image horizontal alignment --- ##### fittingAlgorithm "cover" | "scale\_down" | undefined Image fitting algorithm --- function ### addRecommIdQueryParam Utility function to append `recombee_recomm_id` parameter to an url string. For usage in widget template to construct item link URL. type ### Recommendation Single recommendation item #### Properties ##### id string Item ID --- ##### values { \[key: string\]: any; } | undefined Item properties --- 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. --- type ### CarouselWidgetProps Carousel Widget React Component configuration properties #### Properties ##### apiClient ApiClient Instance of Recombee JS API Client. See[Example](#client-initialization). --- ##### createRequest CreateRequestFunction Request factory function. See[Quick Example](#client-initialization) or visit[API Reference](/api) for overview of available requests. --- ##### onRecommResponse WidgetRecommResponseCallback | undefined Callback function allowing to intercept and inspect recommendation request+response made by widget. ``` import React from "react"; import { } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : ({ , }) => { // use data from request and response for any purpose, i.e. internal tracking }, }); ``` --- ##### deduplicationPartitionKey string | undefined A string key specifying a group of widgets, in which recommendation results will be deduplicated. By default, all widgets belong to a single group so all results from the same database are deduplicated. --- ##### 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](#custom-css). --- ##### classNameDisableDefault boolean | undefined Disables default classes of widget wrapper element. There are some default class names with essential styles applied to the widget wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### contentClassName string | undefined Custom classes of content wrapper element. See[Custom CSS](#custom-css). --- ##### contentClassNameDisableDefault boolean | undefined Disables default classes of content wrapper element. There are some default class names with essential styles applied to the content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### itemWrapperClassName string | undefined Custom classes of item wrapper element. See[Custom CSS](#custom-css). --- ##### itemWrapperClassNameDisableDefault boolean | undefined Disables default classes of item wrapper element. There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### SourceItemComponent ((props: { state: CarouselWidgetState; source?: Recommendation | null | undefined; }) => ReactNode) | undefined A component rendering a source recommended item when using Composite Scenario. --- ##### 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) | undefined Component responsible for rendering the widget markup. Example in which the passed component wraps the default carousel component with additional custom HTML. ``` import React from "react"; import { , , , } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : () => { return `

Recommended

<${} ...${} />
`; }, }); ``` This property also allows to fully cutomize the carousel HTML in extreme cases. ``` import React from "react"; import { , } from "@recombee/carousel-widget-js"; ({ // ...ommited code... : () => { return `
// Use carouselProps.state.items array to loop over items
`; }, }); ``` --- class ### CarouselWidgetState Exposes internal state data of the widget to be used in customizable components #### Properties ##### wrapperRef ObservableRef React ref necessary to control the carousel wrapper element. See[Customization Example](#api/CarouselWidgetProps.CarouselComponent). --- ##### contentRef ObservableRef React ref necessary to control the carousel content element. See[Customization Example](#api/CarouselWidgetProps.CarouselComponent). --- ##### items { key: string; entity: Recommendation; }\[\] Array of items to show in the carousel. --- ##### sourceItem Recommendation | null | undefined 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 ### 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](#custom-css). --- ##### classNameDisableDefault boolean | undefined Disables default classes of widget wrapper element. There are some default class names with essential styles applied to the widget wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### contentClassName string | undefined Custom classes of content wrapper element. See[Custom CSS](#custom-css). --- ##### contentClassNameDisableDefault boolean | undefined Disables default classes of content wrapper element. There are some default class names with essential styles applied to the content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### itemWrapperClassName string | undefined Custom classes of item wrapper element. See[Custom CSS](#custom-css). --- ##### itemWrapperClassNameDisableDefault boolean | undefined Disables default classes of item wrapper element. There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css). --- ##### SourceItemComponent ((props: { state: CarouselWidgetState; source?: Recommendation | null | undefined; }) => ElementType) | undefined A component rendering a source recommended item when using Composite Scenario. --- ##### 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. ---