Build recommendation interfaces (Shopify Hydrogen)

This is for:

Developer

To build a recommendation interface with Coveo Headless and Shopify Hydrogen, you need to use Recommendations controller hooks, create recommendation components, and display recommendations through a recommendation provider.

The code snippets in this article have been simplified to focus on recommendations. To see complete examples, follow the link in each section.

Prerequisites

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

  1. Understand how recommendation interfaces work.

  2. Create recommendation configurations.

Define and retrieve the target recommendation controller hooks

When defining your commerce engine, leverage the defineRecommendations functions to define and retrieve the target recommendation hooks.

import {
  // ...
  defineRecommendations,
  // ...
} from '@coveo/headless-react/ssr-commerce';

export default {
  // ...
  controllers: {
    // ...
    homepageRecommendations: defineRecommendations({ 1
      options: {
            slotId: '9a75d3ba-c053-40bf-b881-6d2d3f8472db'
        },
    }),
    cartRecommendations: defineRecommendations({
      options: {
            slotId: '5a93e231-3b58-4dd2-a00b-667e4fd62c55'
        },
    }),
    pdpRecommendationsLowerCarousel: defineRecommendations({
      options: {
            slotId: 'a24b0e9c-a8d2-4d4f-be76-5962160504e2'
        },
    }),
    pdpRecommendationsUpperCarousel: defineRecommendations({
      options: {
            slotId: '05848244-5c01-4846-b280-ff63f5530733'
        },
    }),
    // ...
  }
} satisfies CommerceEngineDefinitionOptions;
1 For each target recommendation controller hook, specify the slotId of the recommendation slot configuration.

For the full example, see coveo-engine.ts.

Create recommendation components

Create recommendation components that use the target recommendation controller hooks. The following is an example implementation of the homepageRecommendations strategy, which showcases featured products as cards on the home page.

import {useHomepageRecommendations} from '@/lib/coveo.engine';
import {ProductCard} from '../Products/ProductCard';

export function Recommendations() {
  const homepageRecommendations = useHomepageRecommendations();

  return (
    <div>
      {homepageRecommendations.state.products.map((recommendation) => ( 1
        <div key={recommendation.permanentid}>
          <ProductCard
            product={recommendation}
            onSelect={
              homepageRecommendations.methods?.interactiveProduct({ 2
                options: {product: recommendation},
              }).select
            }
          />
        </div>
      ))}
    </div>
  );
}
1 Map each product recommendation to a display component, ProductCard.
2 Use a product card component that calls the interactiveProduct function to log click events when the user selects the product and to handle navigation.

For the full example, see Recommendations.tsx.

Display recommendations with your recommendation provider

When displaying recommendation components on a page, ensure that they’re wrapped in a recommendation provider. The following showcases the home page of the Barca Sports example store with the homepageRecommendations component, simplified to focus on recommendations.

// ...
import {Recommendations} from '@/components/Homepage/Recommendations';
import {RecommendationProvider} from '@/components/Search/Context';
import {recommendationEngineDefinition} from '@/lib/coveo.engine';
import {ServerSideNavigatorContextProvider} from '@/lib/coveo.engine/navigation';

// ...
export async function loader({request, context}: LoaderFunctionArgs) {
  engineDefinition.recommendationEngineDefinition.setNavigatorContextProvider(
    () => new ServerSideNavigatorContextProvider(request), 1
  );
  // ...
  const recommendationStaticState = await fetchRecommendationStaticState({ 2
      context,
      request,
      k: ['homepageRecommendations'],
    });

  return recommendationStaticState;
}

export default function Homepage() {
  const data = useLoaderData<typeof loader>();

  return (
    // ...
        <RecommendationProvider 3
          staticState={data.recommendationStaticState}
          navigatorContext={new ClientSideNavigatorContextProvider()}
        >
          <Recommendations />
        </RecommendationProvider>
    // ...
  );
}
1 Create a navigation context provider.
2 Fetch the static state for recommendations.
3 Wrap your recommendations component with your recommendation provider.

For the full example, see ($locale)._index.tsx.