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

Installation

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

pnpm add @recombee/grid-widget-react@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.

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 {  } 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.

TypeScript JavaScript

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

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:

TypeScript JavaScript

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

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 {
  ,
  ,
  ,
  ,
} from "@recombee/grid-widget-react";
import "@recombee/grid-widget-react/dist/styles.css";

export default () => {
  return (
    < ="@container">
      <
        ={}
        ={}
        ="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)]"
        ="min-h-[260px]"
        ={() => (
          <
            ={(
              `${.?.?.link}`,
              ..,
            )}
            ={
              <
                ={`${.?.?.images?.[0]}`}
                ={600}
                ={400}
              />
            }
            ={`${.?.?.genres?.join(", ")}`}
            ={`${.?.?.title}`}
            ={`${.?.?.year}`}
          />
        )}
      />
    </>
  );
};

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 {
  ,
  ,
  ,
  ,
} from "@recombee/grid-widget-react";
import "@recombee/grid-widget-react/dist/styles.css";

export default () => {
  return (
    < ="@container">
      <
        ={}
        ={}
        ="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"
        ="grid-cols-[repeat(4,1fr)] grid-rows-[repeat(1,1fr)] gap-2 p-1"
        ="min-h-[260px]"
        ={() => (
          <
            ="border-b border-slate-600"
            ="text-center"
            ={(
              `${.?.?.link}`,
              ..,
            )}
            ={
              <
                ={`${.?.?.images?.[0]}`}
                ={600}
                ={400}
              />
            }
            ={`${.?.?.genres?.join(", ")}`}
            ={`${.?.?.title}`}
            ={`${.?.?.year}`}
          />
        )}
      />
    </>
  );
};

Copy

Custom Templates

Recombee Widgets support full customization of internal components such as the appearance of the recommended items.

You can provide your own components via props like ItemComponent to control the structure, styling, and behavior of the widget.

This flexibility allows you to adapt the widget's appearance and functionality to match your design and user experience requirements.

Custom Item

TypeScript + ESM JavaScript + ESM

import { ,  } from "@recombee/grid-widget-react";
import "@recombee/grid-widget-react/dist/styles.css";

export default () => {
  return (
    <
      ={}
      ={}
      ="min-h-[310px]"
      ={() => (
        < ="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
            </>
          </>
        </>
      )}
    />
  );
};

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 {  } from "@recombee/carousel-widget-react";

<
  // ...ommited code...
  ={({ ,  }) => {
    // 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 | "layout" | 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.