Build recommendation interfaces (CSR)

This is for:

Developer

In this article

Prerequisites
Initialize the controller
Use the controller in a component

You can use the Headless Recommendations controller to retrieve recommendations.

You can also use the Recommendations controller and its sub-controllers to assemble recommendations interfaces in your project.

A complete example, including a sample implementation of the recommendation interface, is available in the Headless repository.

Prerequisites

Before you begin building your recommendation interfaces, make sure you:

Initialize the controller

Each Recommendations controller must point to a specific recommendation slot configuration through the slotId, which is defined when initializing the controller. There can be multiple recommendation interfaces on the same page, each pointing to a different recommendation slot and thus using a different controller instance.

The slotId is the unique identifier of the slot you want to retrieve recommendations for. This corresponds to the id field of the recommendation slot configuration you’ve created.

Do the following to initialize the Recommendations controller:

import { engine } from './Engine';
import {buildRecommendations} from '@coveo/headless-commerce';

const recommendationsController = buildRecommendations(engine, { 
    options: {slotId: 'af4fb7ba-6641-4b67-9cf9-be67e9f30174'},
});

Create an instance of the Recommendations controller by passing the previously initialized engine instance and the options object, which contains the slotId of the slot that you want to retrieve recommendations for.

Note

Depending on the seedType used in the recommendation slot configuration, you might need to pass additional details in the options object. For more details, see Recommendations based on configured strategy.

The Recommendations controller provides a refresh method that you can call to fetch new recommendations for the slot.

Use the controller in a component

Once the controller is initialized, it can be used in a component to display recommendations:

import {Cart, Recommendations} from '@coveo/headless/commerce';
import {useEffect, useState} from 'react';
import ProductList from '../../product-list/product-list';
import Pagination from '../pagination/pagination';

interface IRecommendationsInterfaceProps {
  recommendationsController: Recommendations; 
  cartController: Cart;
  navigate: (pathName: string) => void;
}

export default function RecommendationsInterface(
  props: IRecommendationsInterfaceProps
) {
  const {recommendationsController, cartController, navigate} = props;

  const [recommendationsState, setRecommendationsState] = useState(
    recommendationsController.state
  );

  useEffect(() => { 
    recommendationsController.subscribe(() => {
      setRecommendationsState(recommendationsController.state);
    });
  }, [recommendationsController]);

  return (
    <div className="RecommendationsInterface">
      <h3 className="RecommendationsHeadline">
        {recommendationsState.headline} 
      </h3>
      <ProductList 
        products={recommendationsState.products}
        cartController={cartController}
        controllerBuilder={recommendationsController.interactiveProduct}
        navigate={navigate}
      />
      <Pagination controller={recommendationsController.pagination()} /> 
    </div>
  );
}

	Pass an instance of the `Recommendations` controller. This controller and its sub-controllers will be used to fetch and display the recommendations.
	Subscribe to the controller state to update the component when the recommendations change.
	Display the `headline` returned by the recommendation slot.
	Access the current recommendations by reading the `products` field from the controller state. This example uses a custom `ProductList` component to display the recommendations.
	Access the pagination sub-controller to display pagination controls.