React API

The React API provides components and hooks for integrating Netup recommendations into your React application.

Import

import {
  PublishingZone,
  PublishingZoneComponent,
  PublishingZoneTypeEnum,
  NetupRecommendation,
  NetupRecommendationProps,
  NetupProductItemWrapper,
  NetupProvider,
  useNetup,
} from "@front-commerce/netup/react";

Components

NetupProvider

Context provider that manages Netup state and provides recommendation data to child components.

Props

interface NetupProviderProps {
  children: React.ReactNode;
}

Usage

app/root.tsx

import { NetupProvider } from "@front-commerce/netup/react";

export default function App() {
  return <NetupProvider>{/* Your app components */}</NetupProvider>;
}

Behavior

• State Management: Maintains recommendations received from Netup
• Event Listening: Automatically listens for recommendation events
• Disabled State: Provides warning functions when Netup is disabled
• Data Merging: Merges new recommendations with existing ones, replacing duplicates by zone ID

PublishingZone

Component that displays recommendations for a specific zone type.

Props

interface PublishingZoneProps {
  type: PublishingZoneTypeEnum;
  RecommendationComponent?: React.ComponentType<NetupRecommendationProps>;
}

Parameters

type: PublishingZoneTypeEnum

Required. The type of publishing zone to display recommendations for.

See PublishingZoneTypeEnum for available values.

RecommendationComponent?: React.ComponentType<NetupRecommendationProps>

Optional. Custom component to render each recommendation. If not provided, uses the default recommendation component.

Usage

Basic Usage:

import {
  PublishingZone,
  PublishingZoneTypeEnum,
} from "@front-commerce/netup/react";

function HomePage() {
  return (
    <div>
      <h1>Welcome</h1>
      <PublishingZone type={PublishingZoneTypeEnum.homePage} />
    </div>
  );
}

With Custom Component:

warning

Netup Tracking Requirement Custom recommendation components MUST wrap each product item with NetupProductItemWrapper for proper Netup tracking.

app/components/CustomRecommendation.tsx

import { useCallback } from "react";
import {
  PublishingZone,
  PublishingZoneTypeEnum,
  NetupRecommendationProps,
  NetupProductItemWrapper,
} from "@front-commerce/netup/react";
import ProductList from "theme/modules/ProductList/ProductList/ProductList";

function CustomRecommendation({ recommendation }: NetupRecommendationProps) {
  // Create wrapper that includes the publishing zone ID
  const WrapperWithZoneId = useCallback(
    ({ product, children }: { product: any; children: React.ReactNode }) => {
      return (
        <NetupProductItemWrapper
          product={product}
          zoneId={recommendation.publishingZoneId}
        >
          {children}
        </NetupProductItemWrapper>
      );
    },
    [recommendation.publishingZoneId]
  );

  return (
    <div className="custom-rec">
      <h3>{recommendation.json.catchphrase}</h3>
      <ProductList
        skus={recommendation.json.products}
        ProductItemWrapper={WrapperWithZoneId}
      />
    </div>
  );
}

function ProductPage() {
  return (
    <div>
      <PublishingZone
        type={PublishingZoneTypeEnum.productPage}
        RecommendationComponent={CustomRecommendation}
      />
    </div>
  );
}

Behavior

• Zone Filtering: Only displays recommendations matching the specified type
• Configuration Check: Returns null if Netup is disabled
• Empty State: Returns null if no recommendations are available for the zone type
• Multiple Zones: Handles multiple publishing zones of the same type
• DOM Attributes: Adds data-wsb-used="true" attribute for Netup integration

NetupProductItemWrapper

Component that wraps individual product items with Netup tracking elements. Required for custom recommendation components.

Props

interface NetupProductItemWrapperProps {
  product: { sku: string };
  zoneId: string;
  children: React.ReactNode;
}

Parameters

product: { sku: string }

Required. Product object containing at minimum the SKU for identification.

zoneId: string

Required. The publishing zone ID where this product recommendation appears. Use recommendation.publishingZoneId from the recommendation data.

children: React.ReactNode

Required. The product component to wrap with tracking elements.

Usage

<NetupProductItemWrapper product={{ sku: "ABC123" }} zoneId="ZP1">
  <ProductCard sku="ABC123" />
</NetupProductItemWrapper>

Behavior

• Unique ID: Creates ID in format {productSku}@{zoneId}
• Tracking Class: Adds wsbRecommendation class for Netup scripts
• Pass-through: Renders children unchanged inside the tracking wrapper

Hooks

useNetup

Hook to access the Netup context and recommendation data.

Signature

function useNetup(): NetupContextValue;

Returns

interface NetupContextValue {
  recommendations: NetupRecommendation[];
  getRecommendationsForZone: (zoneId: string) => NetupRecommendation | null;
  getRecommendationsForZones: (zoneIds: string[]) => NetupRecommendation[];
}

Usage

import { useNetup } from "@front-commerce/netup/react";

function RecommendationStats() {
  const { recommendations, getRecommendationsForZone } = useNetup();

  return (
    <div>
      <p>Total recommendations: {recommendations.length}</p>
      <button
        onClick={() => {
          const homeRec = getRecommendationsForZone("ZH1");
          console.log("Home recommendations:", homeRec);
        }}
      >
        Check Home Zone
      </button>
    </div>
  );
}

Context Methods

getRecommendationsForZone(zoneId: string)

Returns a single recommendation for the specified zone ID.

Parameters:

• zoneId: string - The publishing zone ID to search for

Returns: NetupRecommendation | null

const homeRecommendation = getRecommendationsForZone("ZH1");
if (homeRecommendation) {
  console.log("Products:", homeRecommendation.json.products);
}

getRecommendationsForZones(zoneIds: string[])

Returns recommendations for multiple zone IDs.

Parameters:

• zoneIds: string[] - Array of zone IDs to search for

Returns: NetupRecommendation[]

const productRecommendations = getRecommendationsForZones(["ZP1", "ZP2"]);
console.log(`Found ${productRecommendations.length} product recommendations`);

Types and Enums

PublishingZoneTypeEnum

Enum defining the types of publishing zones supported by Netup.

enum PublishingZoneTypeEnum {
  productPage = "productPage",
  homePage = "homePage",
  cartPage = "cartPage",
  productAddedPopInCrosssells = "productAddedPopInCrosssells",
  categoryPage = "categoryPage",
}

Values

Value	Description	Usage
productPage	Product detail page recommendations	Related products, upsells
homePage	Homepage recommendations	Featured products, trending items
cartPage	Shopping cart recommendations	Add-on products, alternatives
productAddedPopInCrosssells	Cross-sell popup after adding to cart	Complementary products
categoryPage	Category page recommendations	Related categories, featured products

NetupRecommendation

Type representing a recommendation from Netup.

interface NetupRecommendation {
  publishingZoneId: string;
  json: {
    catchphrase?: string;
    products: string[];
  };
}

Properties

publishingZoneId: string

The unique identifier for the publishing zone this recommendation belongs to.

json.catchphrase?: string

Optional marketing message or title for the recommendation.

json.products: string[]

Array of product SKUs recommended for this zone.

NetupRecommendationProps

Props interface for custom recommendation components.

interface NetupRecommendationProps {
  recommendation: NetupRecommendation;
}

Usage

function MyRecommendation({ recommendation }: NetupRecommendationProps) {
  const { publishingZoneId, json } = recommendation;

  return (
    <section data-zone={publishingZoneId}>
      {json.catchphrase && <h2>{json.catchphrase}</h2>}
      <ProductGrid skus={json.products} />
    </section>
  );
}