useRecs

Overview

The useRecs hook is the primary hook for interacting with the Recommendations functionality. It provides access to recommendation data, API functions, and all state related to product recommendations. This hook must be used within a component that is wrapped by the UnbxdRecsCSRWrapper.

⚠️

Important:

The useRecs hook must be used within a component that is wrapped by UnbxdRecsCSRWrapper. Using it outside this context will result in an error.

Usage

import { useRecs } from "@unbxd-ui/react-recs-hooks";

Code Example

const RecommendationsDisplay = () => {
    const {
        recsApiCall,
        getSingleWidgetResponse,
        apiResponse,
        isLoading,
        updateLoading,
    } = useRecs();
    
    // Get recommendations for a specific widget
    const homeWidget = getSingleWidgetResponse("HOME_WIDGET_1");
    
    if (isLoading) {
        return <div>Loading recommendations...</div>;
    }
    
    return (
        <div>
            {homeWidget && (
                <div>
                    <h2>{homeWidget.title}</h2>
                    {homeWidget.products.map(product => (
                        <ProductCard key={product.uniqueId} product={product} />
                    ))}
                </div>
            )}
        </div>
    );
};

Hook API

Return Values

apiResponse

Array

Array of recommendation widgets returned from the API. Each widget contains recommendation data including products, title, and widget configuration.

API Response Structure:

[
    {
        widgetId: "HOME_WIDGET_1",
        title: "Recommended for You",
        products: [
            {
                uniqueId: "product123",
                title: "Product Name",
                price: 99.99,
                imageUrl: "https://example.com/image.jpg",
                // ... other product fields
            }
        ],
        // ... other widget properties
    }
]

Usage:

const { apiResponse } = useRecs();
 
// Access all widgets
apiResponse.forEach(widget => {
    console.log(widget.widgetId, widget.products);
});

isLoading

boolean

Boolean indicating whether the recommendations API call is currently in progress.

Usage:

const { isLoading } = useRecs();
 
if (isLoading) {
    return <LoadingSpinner />;
}

recsApiCall

function

Manually triggers the recommendations API call. Note: The API call is automatically triggered by the DataFetcher when the wrapper is initialized or when relevant props change.

Usage:

const { recsApiCall } = useRecs();
 
// Manually trigger API call
const refreshRecommendations = () => {
    recsApiCall();
};

Behavior:

Sets loading state to true
Fetches recommendations from the API
Updates apiResponse with the fetched data
Sets loading state to false on completion
Handles errors and updates error state if the call fails

getSingleWidgetResponse

function

Retrieves a specific widget's recommendation data by widget ID.

Parameters:

widgetId string - The ID of the widget to retrieve

Returns:

Widget object if found, null if not found

const { getSingleWidgetResponse } = useRecs();
 
// Get a specific widget's recommendations
const homeWidget = getSingleWidgetResponse("HOME_WIDGET_1");
 
if (homeWidget) {
    console.log("Widget title:", homeWidget.title);
    console.log("Products:", homeWidget.products);
}

Behavior:

Filters the apiResponse array to find the widget with matching widgetId
Returns the first matching widget object
Returns null if no widget is found or if apiResponse is empty

updateLoading

function

Toggles the loading state manually.

Usage:

const { updateLoading } = useRecs();
 
// Toggle loading state
updateLoading();

Behavior:

Toggles the current isLoading value (true → false, false → true)

UnbxdRecsCSRWrapper Widget