Widget

Overview

The Widget component is a core UI component of the Recommendations SDK that displays product recommendation widgets. It automatically fetches and renders recommendation data from the API based on the specified widget ID. The component supports custom title, product card, and loader components, allowing for complete customization while maintaining the core recommendation functionality.

⚠️

Note:

The Widget component must be used within the UnbxdRecsCSRWrapper to ensure that the component has access to recommendation data and works properly.

Usage

// Import the component
import { Widget } from "@unbxd-ui/react-recs-components";
 
// Import styles (optional)
import "@unbxd-ui/react-recs-components/styles/widget.css";

Code Example

import { UnbxdRecsCSRWrapper } from "@unbxd-ui/react-recs-hooks";
import { Widget } from "@unbxd-ui/react-recs-components";
import "@unbxd-ui/react-recs-components/styles/widget.css";
 
function RecommendationsApp() {
  return (
    <UnbxdRecsCSRWrapper 
      sitekey="YOUR_SITE_KEY" 
      apikey="YOUR_API_KEY"
      extraParams={{
        pageType: "HOME",
        uid: "user123"
      }}
      onEvent={({ type, message, value, state }) => {
        console.log("Recs event:", type, message);
      }}
    >
      <div className="recommendations-container">
        <Widget widgetId="HOME_WIDGET_1" />
      </div>
    </UnbxdRecsCSRWrapper>
  );
}

Props

widgetId

required

string

This is the id using which sdk knows which widget is needed to be shown.
This needs to be the id which

<Widget widgetId="HOME_WIDGET_1" />

TitleComponent

optional

React Component

A custom React component to display the widget title.
Receives widget (the full widget object) and widgetTitle (CSS class name) as props.
Default Value: Displays the widget's widgetTitle property in a styled div.

const CustomTitle = ({ widget, widgetTitle }) => {
  return (
    <h2 className={widgetTitle}>
      {widget?.widgetTitle || "Recommendations"}
    </h2>
  );
};
 
<Widget 
  widgetId="HOME_WIDGET_1" 
  TitleComponent={CustomTitle}
/>

Props received by TitleComponent:

widget - The complete widget object containing title, products, and metadata
widgetTitle - CSS class name for styling the title

ProductCardComponent

optional

React Component

A custom React component to display individual product cards.
Receives item (product data) and widgetItem (CSS class name) as props.
This component is rendered for each product in the widget's recommendations array.
Default Value: Displays a simple product card with image, title, and price.

const CustomProductCard = ({ item, widgetItem }) => {
  return (
    <div className={widgetItem} key={item.uniqueId}>
      <img src={item.imageUrl} alt={item.title} />
      <h3>{item.title}</h3>
      <p>${item.price}</p>
      <button onClick={() => addToCart(item)}>Add to Cart</button>
    </div>
  );
};
 
<Widget 
  widgetId="HOME_WIDGET_1" 
  ProductCardComponent={CustomProductCard}
/>

Props received by ProductCardComponent:

item - The product object containing product data (uniqueId, title, price, imageUrl, etc.)
widgetItem - CSS class name for styling the product card

Product Object Structure:

{
  uniqueId: "product123",
  title: "Product Name",
  price: 99.99,
  imageUrl: "https://example.com/image.jpg",
  // ... other product fields
}

LoaderComponent

optional

React Component

A custom React component to display while recommendations are loading.
Receives cssClass object with loaderClass property as props.
Default Value: Displays "Loading..." text in a styled div.

const CustomLoader = ({ cssClass }) => {
  const { loaderClass } = cssClass;
  return (
    <div className={loaderClass}>
      <Spinner />
      <p>Loading recommendations...</p>
    </div>
  );
};
 
<Widget 
  widgetId="HOME_WIDGET_1" 
  LoaderComponent={CustomLoader}
/>

Props received by LoaderComponent:

cssClass - Object containing loaderClass property with CSS class name for styling

styles

optional

object

Custom CSS class names to override default styling.
Allows you to customize the appearance of different parts of the widget.
Default Value:

{
  widgetContainer: "widget-container",
  widgetTitle: "widget-title",
  widgetScrollContainer: "widget-scroll-container",
  widgetItem: "widget-item"
}

<Widget 
  widgetId="HOME_WIDGET_1" 
  styles={{
    widgetContainer: "my-custom-container",
    widgetTitle: "my-custom-title",
    widgetScrollContainer: "my-custom-scroll",
    widgetItem: "my-custom-item"
  }}
/>

Available Style Properties:

widgetContainer - CSS class for the main widget container
widgetTitle - CSS class for the widget title element
widgetScrollContainer - CSS class for the container holding all product cards
widgetItem - CSS class for individual product card elements

Styling

The component comes with default CSS classes that you can override using the styles prop. You can also import the default styles:

import "@unbxd-ui/react-recs-components/styles/widget.css";

Then customize them in your CSS:

.widget-container {
  padding: 20px;
  background: #f5f5f5;
}
 
.widget-title {
  font-size: 24px;
  font-weight: bold;
  margin-bottom: 20px;
}
 
.widget-scroll-container {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 20px;
}
 
.widget-item {
  background: white;
  padding: 15px;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

useRecs