# Carousel Widget (React)
> Source: https://docs.recombee.com/widget-sdks/carousel-widget-react
> For the complete documentation index, see [llms.txt](/llms.txt).
**Table of contents**
* [ Installation ](#install)
* [ Client Initialization ](#client-initialization)
* [ Providing User ID ](#providing-user-id)
* [ Basic Example ](#basic-example)
* [ Custom CSS ](#custom-css)
* [ Custom Templates ](#custom-templates)
* [ Custom Item ](#custom-item)
* [ Custom Arrows ](#custom-arrows)
* [ Full Customization ](#full-customization)
* [ Overriding Base Classes ](#overriding-base-classes)
* [ Composite Recommendations ](#composite-recommendations)
* [API Reference](#api)
* [CarouselWidget](#api/CarouselWidget)
* [CarouselWidgetProps](#api/CarouselWidgetProps)
* [CarouselWidgetState](#api/CarouselWidgetState)
* [DefaultItem](#api/DefaultItem)
* [DefaultItemProps](#api/DefaultItemProps)
* [ItemImage](#api/ItemImage)
* [ItemImageProps](#api/ItemImageProps)
* [Recommendation](#api/Recommendation)
* [addRecommIdQueryParam](#api/addRecommIdQueryParam)
* [DefaultCarousel](#api/DefaultCarousel)
* [DefaultCarouselProps](#api/DefaultCarouselProps)
* [DefaultCarouselArrow](#api/DefaultCarouselArrow)
* [CarouselArrowProps](#api/CarouselArrowProps)
* [CreateRequestFunction](#api/CreateRequestFunction)
* [FetchContentOptions](#api/FetchContentOptions)
# 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.2.18 and the API can change. Please specify exact version when installing.
## Installation
Install `@recombee/carousel-widget-react@0.2.18` and `recombee-js-api-client`packages using your preferred NPM package manager. This example is using`pnpm`.
```
pnpm add @recombee/carousel-widget-react@0.2.18 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-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
<
={}
={}
="gap-4 p-6"
="min-w-[240px] min-h-[260px]"
={() => (
<
={(
.?.?.link,
..,
)}
={
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
}
={`${.?.?.genres?.join(", ")}`}
={`${.?.?.title}`}
={`${.?.?.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):
```
```
This is handy to understand how to customize the widget to full potential.
### Setting own classes
```
import {
,
,
,
,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
<
={}
={}
="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]"
={() => (
<
="border-b border-slate-600"
="text-center"
={(
.?.?.link,
..,
)}
={
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
}
={`${.?.?.genres?.join(", ")}`}
={`${.?.?.title}`}
={`${.?.?.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/CarouselWidgetProps.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-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
<
={}
={}
="gap-4 p-6"
="min-h-[290px] w-[200px]"
={() => (
< ="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white">
< ="relative overflow-hidden bg-cover bg-no-repeat">
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
{.?.?.["genres"]?.includes("drama") && (
< ="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white">
Drama
)}
{.?.?.["genres"]?.includes("science_fiction") && (
< ="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white">
Sci-Fi
)}
< ="p-3">
< ="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]">
{`${.?.?.genres?.join(", ")}`}
< ="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
{`${.?.?.title}`}
< ="line-clamp-4 pb-3 text-base text-[#3f91ff]">
{`${.?.?.year}`}
< ="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]">
Play
)}
/>
);
};
```
### Custom Arrows
```
import {
,
,
,
,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
<
={}
={}
="gap-4 p-6"
="min-h-[400px] w-[400px]"
={() => {
if (
. === "left" &&
...
) {
return (
<
="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]"
="button"
={...}
>
prev
);
}
if (
. === "right" &&
...
) {
return (
<
="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]"
="button"
={...}
>
next
);
}
}}
={() => (
<
={(
.?.?.link,
..,
)}
={
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
}
={`${.?.?.genres?.join(", ")}`}
={`${.?.?.title}`}
={`${.?.?.year}`}
/>
)}
/>
);
};
```
### Full Customization
```
import {
,
,
,
,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => (
<
={}
={}
={() => null}
={() => (
< ="p-4">
<
{...}
="gap-1"
="min-h-[240px] w-[200px]"
/>
< ="flex justify-end gap-2 pt-4">
< ="flex gap-2">
<
={!...}
={...}
>
PREV
<
={!...}
={...}
>
NEXT
)}
={() => (
< ="overflow-hidden rounded-lg border-[#ededed] bg-white text-[#282b30] dark:border-none dark:bg-transparent dark:text-white">
< ="relative overflow-hidden bg-cover bg-no-repeat">
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
{.?.?.["genres"]?.includes("drama") && (
< ="absolute top-3 left-3 bg-[#3f91ff] px-2 text-xs/[1.67] font-semibold text-white">
Drama
)}
{.?.?.["genres"]?.includes("science_fiction") && (
< ="absolute top-3 left-3 bg-[#36c696] px-2 text-xs/[1.67] font-semibold text-white">
Sci-Fi
)}
< ="p-3">
< ="mb-1 line-clamp-4 overflow-hidden text-[14px]/[1.43] text-nowrap text-ellipsis text-[#80868f]">
{`${.?.?.genres?.join(", ")}`}
< ="text-md mb-1 overflow-hidden text-nowrap text-ellipsis">
{`${.?.?.title}`}
< ="line-clamp-4 pb-3 text-base text-[#3f91ff]">
{`${.?.?.year}`}
< ="w-full rounded-lg border border-[#ededed] py-2 text-center text-[14px]/[1.43] font-medium text-[#80868f]">
Play
)}
/>
);
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 (
<
={(, {
"opacity-50": .disabled,
})}
{...}
/>
);
}
```
## 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-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
< ="flex justify-center">
< ="w-[40%]">
<
={}
={}
="rb:no-scrollbar flex min-h-[420px] snap-x snap-mandatory content-stretch gap-1 overflow-x-auto p-6"
="min-h-[260px] flex min-w-full flex-grow basis-full snap-center"
={() => (
<
={(
.?.?.link,
..,
)}
={
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
}
={`${.?.?.genres?.join(", ")}`}
={`${.?.?.title}`}
={`${.?.?.year}`}
/>
)}
/>
);
};
```
## Composite Recommendations
Widget SDKs can also be used to render [Composite Recommendations](/scenarios#composite-recommendations). A common use case is displaying [dynamic category- or genre-based rails](/scenarios#fully-personalized-homepage) on the homepage, as well as scenarios such as [Because You Watched](/scenarios#because-you-watched-movie-). The CompositeRecommendation request is called from within the[createRequest](/widget-sdks/carousel-widget-react#api/CarouselWidgetProps.createRequest)function. To render the header (for example, the user’s favorite category or the title of the watched movie), implement the[SourceItemComponent](/widget-sdks/carousel-widget-react#api/CarouselWidgetProps.SourceItemComponent).
```
const : = ({ }) => {
return new ("top-from-genre-for-you", , {
: { : true },
});
};
import {
,
,
,
,
} from "@recombee/carousel-widget-react";
import "@recombee/carousel-widget-react/dist/styles.css";
export default () => {
return (
<
={}
={}
="gap-4 p-6"
="min-w-[240px] min-h-[260px]"
={({ }) => {
return ? (
< ="px-6">
< ="mt-5 mb-0">Because you like {?.}
) : null;
}}
={() => (
<
={(
.?.?.link,
..,
)}
={
<
={`${.?.?.images?.[0]}`}
={600}
={400}
/>
}
={`${.?.?.genres?.join(", ")}`}
={`${.?.?.title}`}
={`${.?.?.year}`}
/>
)}
/>
);
};
```
## API Reference
const
### CarouselWidget
Carousel widget React Component. See [CarouselWidgetProps](#api/CarouselWidgetProps) for configuration options.
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-react";
<
// ...ommited code...
={({ , }) => {
// use data from request and response for any purpose, i.e. internal tracking
}}
/>;
```
---
##### deduplicationPartitionKey
string | undefined
A string key specifying a group of widgets, in which recommendation results will be deduplicated. By default, all widgets belong to a single group so all results from the same database are deduplicated.
---
##### 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-react";
<
// ...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-react";
<
// ...ommited code...
={() => {
return (
< ={...}>
<>Recommended
< ={...}>
// 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
### DefaultItem
Default Item component provided for basic usage.
interface
### DefaultItemProps
Recommended item component properties.
#### Properties
##### className
string | undefined
Custom classes of item wrapper element. See[Custom CSS](#custom-css).
---
##### classNameDisableBase
boolean | undefined
Disables default classes of item wrapper element.
There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).
---
##### imageWrapperClassName
string | undefined
Custom classes of item image wrapper element. See[Custom CSS](#custom-css).
---
##### imageWrapperClassNameDisableBase
boolean | undefined
Disables default classes of item image wrapper element.
There are some default class names with essential styles applied to the item image wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).
---
##### contentWrapperClassName
string | undefined
Custom classes of item content element. See[Custom CSS](#custom-css).
---
##### result
Recommendation | undefined
A single item recommedation.
---
##### href
string | null | undefined
Item link URL.
---
##### image
ReactNode
Item Image element.
---
##### labelContent
ReactNode
Item content above title. Sets the entire content of an item aside from an image.
---
##### labelContentWrapperClassName
string | undefined
Custom classes of label content wrapper element. See[Custom CSS](#custom-css).
---
##### labelContentWrapperClassNameDisableBase
boolean | undefined
Disables default classes of label content wrapper element.
There are some default class names with essential styles applied to the label content wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).
---
##### title
ReactNode
Item title.
---
##### titleWrapperClassName
string | undefined
Custom classes of title wrapper element. See[Custom CSS](#custom-css).
---
##### titleWrapperClassNameDisableBase
boolean | undefined
Disables default classes of title wrapper element.
There are some default class names with essential styles applied to the title wrapper element. This setting disables them as an escape hatch for customization. See [Custom CSS](#custom-css).
---
##### highlightedContent
ReactNode
Item content under title. Sets the entire content of an item aside from an image.
---
##### highlightedContentWrapperClassName
string | undefined
Custom classes of highlighted content wrapper element. See[Custom CSS](#custom-css).
---
##### highlightedContentWrapperClassNameDisableBase
boolean | undefined
Disables default classes of highlighted content wrapper element.
There are some default class names with essential styles applied to the highlighted content wrapper element. This setting disables them as an escape hatch for customization. See[Custom CSS](#custom-css).
---
##### bottomContent
ReactNode
Any custom content to display at the bottom of the item.
---
const
### ItemImage
Item image component
type
### ItemImageProps
Item Image properties
#### Properties
##### src
string | null | undefined
Image URL
---
##### missingImageSrc
string | undefined
URL of an image to display when the main image could not be loaded.
---
##### className
string | undefined
Image wrapper class name
---
##### imgClassName
string | undefined
Image class name
---
##### width
number | undefined
Image width in pixels
---
##### height
number | undefined
Image height in pixels
---
##### verticalAlignment
"top" | "center" | "bottom" | undefined
Image vertical alignment
---
##### horizontalAlignment
"center" | "left" | "right" | undefined
Image horizontal alignment
---
##### fittingAlgorithm
"cover" | "scale\_down" | undefined
Image fitting algorithm
---
type
### Recommendation
Single recommendation item
#### Properties
##### id
string
Item ID
---
##### values
{ \[key: string\]: any; } | undefined
Item properties
---
function
### addRecommIdQueryParam
Utility function to append `recombee_recomm_id` parameter to an url string. For usage in widget template to construct item link URL.
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.
---
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.
---