Table of contents

Widget SDKs / Grid / Grid Widget (React)

Grid Widget (React)

A React component widget that renders a grid of recommended items, optimized for high-density product presentation.

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/grid-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/grid-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.

Number of items loaded to grid widget is governed by CSS Grid styling which must be provided. See the example code where the grid is defined using utility classes provided by TailwindCSS.

TypeScript + ESM JavaScript + ESM

import {
  const GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget,
  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/grid-widget-react";
import "@recombee/grid-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="@container">
      <const GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget
        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}
        contentClassName?: string | undefinedCustom classes of content wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentClassName="grid-cols-[repeat(1,1fr)] grid-rows-[repeat(4,1fr)] gap-2 @lg:grid-cols-[repeat(2,1fr)] @lg:grid-rows-[repeat(3,1fr)] @xl:grid-cols-[repeat(4,1fr)] @xl:grid-rows-[repeat(2,1fr)]"
        type ItemComponent: React.FC<{
    state: GridWidgetState;
    result: Recommendation;
}>A component rendering a single recommended item.
@publicItemComponent={(props: {
    state: GridWidgetState;
    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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
              props: {
    state: GridWidgetState;
    result: Recommendation;
}props.state: GridWidgetStatestate.GridWidgetState.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
            DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
          />
        )}
      />
    </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
  );
};

Copy

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}">
      <div class="{DefaultItem.className}"></div>
    </div>
    <div class="{itemWrapperClassName}">
      <div class="{DefaultItem.className}"></div>
    </div>
    <div class="{itemWrapperClassName}">
      <div class="{DefaultItem.className}"></div>
    </div>
    ... more items ...
  </div>
</div>

Copy

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

Setting own classes

TypeScript + ESM JavaScript + ESM

import {
  const GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget,
  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/grid-widget-react";
import "@recombee/grid-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="@container">
      <const GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget
        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}
        contentClassName?: string | undefinedCustom classes of content wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publiccontentClassName="grid-cols-[repeat(4,1fr)] grid-rows-[repeat(1,1fr)] gap-2 p-1"
        className?: string | undefinedCustom classes of widget wrapper element. See

{@link 
file://./#custom-css Custom CSS
}
.
@publicclassName="rb:overflow-hidden rb:text-[#282b30] rb:rounded-lg rb:bg-white rb:border rb:border-[#ededed] rb:dark:border-none rb:dark:bg-transparent rb:dark:text-white"
        type ItemComponent: React.FC<{
    state: GridWidgetState;
    result: Recommendation;
}>A component rendering a single recommended item.
@publicItemComponent={(props: {
    state: GridWidgetState;
    result: Recommendation;
}props) => (
          <const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem
            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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.link}`,
              props: {
    state: GridWidgetState;
    result: Recommendation;
}props.state: GridWidgetStatestate.GridWidgetState.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.genres?.join(", ")}`}
            DefaultItemProps.title?: React.ReactNodeItem title.
@publictitle={`${props: {
    state: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.values?: {
    [key: string]: any;
} | undefinedItem properties
@publicvalues?.year}`}
          />
        )}
      />
    </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
  );
};

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 GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget, const ItemImage: React.FunctionComponent<ItemImageProps>Item image component
@publicItemImage } from "@recombee/grid-widget-react";
import "@recombee/grid-widget-react/dist/styles.css";

export default () => {
  return (
    <const GridWidget: React.FunctionComponent<GridWidgetProps>Grid Widget component
@publicGridWidget
      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-[200px]"
      type ItemComponent: React.FC<{
    state: GridWidgetState;
    result: Recommendation;
}>A component rendering a single recommended item.
@publicItemComponent={(props: {
    state: GridWidgetState;
    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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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: GridWidgetState;
    result: Recommendation;
}props.result: Recommendationresult?.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

API Reference

const

GridWidget

Grid Widget component

type

GridWidgetProps

Grid Widget component configuration options

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.

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

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

A component rendering a single recommended item.

class

GridWidgetState

Class exposing internal state of the grid

Properties

items

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

recommId

string | undefined

Id of recommendation response from which the items originated.

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.

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.