@algolia/recommend-react

@algolia/recommend-react

React package for Algolia Recommend.

Installation

yarn add @algolia/recommend-react@experimental
# or
npm install @algolia/recommend-react@experimental

<RelatedProducts />

Component to display related products.

Usage

Default view

import { RelatedProducts } from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function RelatedItem({ item }) {
  return (
    <pre>
      <code>{JSON.stringify(item)}</code>
    </pre>
  );
}

function App({ currentObjectID }) {
  // ...

  return (
    <RelatedProducts
      recommendClient={recommendClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
    />
  );
}

Horizontal slider view

Example with the HorizontalSlider UI component:

import { RelatedProducts } from '@algolia/recommend-react';
import { HorizontalSlider } from '@algolia/ui-components-horizontal-slider-react';
import recommend from '@algolia/recommend';

import '@algolia/ui-components-horizontal-slider-theme';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function RelatedItem({ item }) {
  return (
    <pre>
      <code>{JSON.stringify(item)}</code>
    </pre>
  );
}

function App({ currentObjectID }) {
  // ...

  return (
    <RelatedProducts
      recommendClient={recommendClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
      view={HorizontalSlider}
    />
  );
}

Props

The component accepts all the shared props and the following:

itemComponent

({ item }) => JSX.Element | required

The product component to display.

classNames

RelatedProductsClassNames

type RelatedProductsClassNames = Partial<{
  root: string;
  title: string;
  container: string;
  list: string;
  item: string;
}>;

The class names for the component.

translations

RelatedProductTranslations

type RelatedProductTranslations = Partial<{
  title: string;
  showMore: string;
}>;

The translations for the component.

view

(props: ViewProps) => JSX.Element

type ViewProps<TItem extends RecordWithObjectID> = {
  items: TItem[];
  itemComponent({ item: TItem }): JSX.Element;
};

The view component to render your items into. You can use the HorizontalSlider UI component.

The default implementation is:

function ListView(props) {
  return (
    <div className="auc-Recommend-container">
      <ol className="auc-Recommend-list">
        {props.items.map((item) => (
          <li key={item.objectID} className="auc-Recommend-item">
            <props.itemComponent item={item} />
          </li>
        ))}
      </ol>
    </div>
  );
}

fallbackComponent

() => JSX.Element

The fallback component to render when no recommendations are returned.

children

(props: ChildrenProps) => JSX.Element

type ChildrenProps<TObject> = {
  classNames: RecommendationClassNames;
  recommendations: TObject[];
  translations: Required<RecommendationTranslations>;
  View(props: unknown): JSX.Element;
};

Render function to modify the complete rendering.

The default implementation is:

function defaultRender(props) {
  if (props.recommendations.length === 0) {
    return null;
  }

  return (
    <section className="auc-Recommend">
      {props.translations.title && <h3>{props.translations.title}</h3>}

      <props.View />
    </section>
  );
}

useRelatedProducts

(props: SharedProps) => { recommendations }

Hook to retrieve related products.

Usage

import { useRelatedProducts } from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useRelatedProducts({
    recommendClient,
    indexName,
    objectIDs: [currentObjectID],
  });

  return (
    <div className="auc-Recommend">
      {recommendations.length > 0 && (
        <ol className="auc-Recommend-list">
          {recommendations.map((recommendation) => (
            <li key={recommendation.objectID} className="auc-Recommend-item">
              <pre>
                <code>{JSON.stringify(recommendation)}</code>
              </pre>
            </li>
          ))}
        </ol>
      )}
    </div>
  );
}

Props

The hook accepts all the shared props.

<FrequentlyBoughtTogether />

Component to display frequently bought together products.

Usage

Default view

import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function RelatedItem({ item }) {
  return (
    <pre>
      <code>{JSON.stringify(item)}</code>
    </pre>
  );
}

function App({ currentObjectID }) {
  // ...

  return (
    <FrequentlyBoughtTogether
      recommendClient={recommendClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
    />
  );
}

Horizontal slider view

Example with the HorizontalSlider UI component:

import { FrequentlyBoughtTogether } from '@algolia/recommend-react';
import { HorizontalSlider } from '@algolia/ui-components-horizontal-slider-react';
import recommend from '@algolia/recommend';

import '@algolia/ui-components-horizontal-slider-theme';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function RelatedItem({ item }) {
  return (
    <pre>
      <code>{JSON.stringify(item)}</code>
    </pre>
  );
}

function App({ currentObjectID }) {
  // ...

  return (
    <FrequentlyBoughtTogether
      recommendClient={recommendClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
      view={HorizontalSlider}
    />
  );
}

Props

The component accepts all the shared props and the following:

itemComponent

({ item }) => JSX.Element | required

The product component to display.

classNames

FrequentlyBoughtTogetherClassNames

type FrequentlyBoughtTogetherClassNames = Partial<{
  root: string;
  title: string;
  container: string;
  list: string;
  item: string;
}>;

The class names for the component.

translations

FrequentlyBoughtTogetherTranslations

type FrequentlyBoughtTogetherTranslations = Partial<{
  title: string;
  showMore: string;
}>;

The translations for the component.

view

(props: ViewProps) => JSX.Element

type ViewProps<TItem extends RecordWithObjectID> = {
  items: TItem[];
  itemComponent({ item: TItem }): JSX.Element;
};

The view component to render your items into. You can use the HorizontalSlider UI component.

The default implementation is:

function ListView(props) {
  return (
    <div className="auc-Recommend-container">
      <ol className="auc-Recommend-list">
        {props.items.map((item) => (
          <li key={item.objectID} className="auc-Recommend-item">
            <props.itemComponent item={item} />
          </li>
        ))}
      </ol>
    </div>
  );
}

fallbackComponent

() => JSX.Element

The fallback component to render when no recommendations are returned.

Example with a <RelatedProducts /> fallback:

function RelatedItem({ item }) {
  return (
    <pre>
      <code>{JSON.stringify(item)}</code>
    </pre>
  );
}

function App({ currentObjectID }) {
  return (
    <FrequentlyBoughtTogether
      recommendClient={recommendClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
      fallbackComponent={() => (
        <RelatedProducts
          recommendClient={recommendClient}
          indexName={indexName}
          objectIDs={[currentObjectID]}
          itemComponent={RelatedItem}
        />
      )}
    />
  );
}

children

(props: ChildrenProps) => JSX.Element

type ChildrenProps<TObject> = {
  classNames: RecommendationClassNames;
  recommendations: TObject[];
  translations: Required<RecommendationTranslations>;
  View(props: unknown): JSX.Element;
};

Render function to modify the complete rendering.

The default implementation is:

function defaultRender(props) {
  if (props.recommendations.length === 0) {
    return null;
  }

  return (
    <section className="auc-Recommend">
      {props.translations.title && <h3>{props.translations.title}</h3>}

      <props.View />
    </section>
  );
}

useFrequentlyBoughtTogether

(props: Omit<SharedProps, 'fallbackParameters'>) => { recommendations }

Hook to retrieve frequently bought together products.

Usage

import { useFrequentlyBoughtTogether } from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useFrequentlyBoughtTogether({
    recommendClient,
    indexName,
    objectIDs: [currentObjectID],
  });

  return (
    <div className="auc-Recommend">
      {recommendations.length > 0 && (
        <ol className="auc-Recommend-list">
          {recommendations.map((recommendation) => (
            <li key={recommendation.objectID} className="auc-Recommend-item">
              <pre>
                <code>{JSON.stringify(recommendation)}</code>
              </pre>
            </li>
          ))}
        </ol>
      )}
    </div>
  );
}

Props

The hook accepts all the shared props.

useRecommendations

(props: SharedProps & { model: RecommendationModel }) => { recommendations }

Generic hook to retrieve hits from an AI model.

Usage

import { useRecommendations } from '@algolia/recommend-react';
import recommend from '@algolia/recommend';

const appId = 'HYDY1KWTWB';
const apiKey = '28cf6d38411215e2eef188e635216508';
const indexName = 'gstar_demo_test';

const recommendClient = recommend(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useRecommendations({
    model: 'related-products',
    recommendClient,
    indexName,
    objectIDs: [currentObjectID],
  });

  return (
    <div className="auc-Recommend">
      {recommendations.length > 0 && (
        <ol className="auc-Recommend-list">
          {recommendations.map((recommendation) => (
            <li key={recommendation.objectID} className="auc-Recommend-item">
              <pre>
                <code>{JSON.stringify(recommendation)}</code>
              </pre>
            </li>
          ))}
        </ol>
      )}
    </div>
  );
}

Props

The hook accepts all the shared props and the following:

model

"related-products" | "bought-together" | required

The name of the Recommendation model to use.

Shared props

recommendClient

recommendClient | required

The initialized Algolia search client.

indexName

string | required

The name of the products index.

objectIDs

string[] | required

An array of objectIDs of the products to get recommendations from.

maxRecommendations

number | defaults to the maximum number of recommendations available

The number of recommendations to retrieve.

fallbackParameters

Omit<SearchOptions, 'page' | 'hitsPerPage' | 'offset' | 'length'>

Additional filters to use as fallback should there not be enough recommendations.

queryParameters

SearchParameters | defaults to { analytics: false, enableABTest: false }

List of search parameters to send.

transformItems

(Array<RecordWithObjectID<TItem>>) => Array<RecordWithObjectID<TItem>>

type RecordWithObjectID<TItem> = TItem & {
  objectID: string;
};

Function to transform the items retrieved by Algolia. It's useful to edit, add, remove or reorder them.

Changelog

1.0.0-experimental.5 (2021-06-23)

Bug Fixes

• recommend: ignore items type in components (#37) (63121fa)

Features

• recommend: leverage the new Recommend API client (#40) (618ee07)