@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 algoliasearch from 'algoliasearch';

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

const searchClient = algoliasearch(appId, apiKey);

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

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

  return (
    <RelatedProducts
      searchClient={searchClient}
      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 algoliasearch from 'algoliasearch';

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

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

const searchClient = algoliasearch(appId, apiKey);

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

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

  return (
    <RelatedProducts
      searchClient={searchClient}
      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 algoliasearch from 'algoliasearch';

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

const searchClient = algoliasearch(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useRelatedProducts({
    searchClient,
    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 algoliasearch from 'algoliasearch';

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

const searchClient = algoliasearch(appId, apiKey);

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

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

  return (
    <FrequentlyBoughtTogether
      searchClient={searchClient}
      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 algoliasearch from 'algoliasearch';

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

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

const searchClient = algoliasearch(appId, apiKey);

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

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

  return (
    <FrequentlyBoughtTogether
      searchClient={searchClient}
      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
      searchClient={searchClient}
      indexName={indexName}
      objectIDs={[currentObjectID]}
      itemComponent={RelatedItem}
      fallbackComponent={() => (
        <RelatedProducts
          searchClient={searchClient}
          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, 'fallbackFilters'>) => { recommendations }

Hook to retrieve frequently bought together products.

Usage

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

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

const searchClient = algoliasearch(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useFrequentlyBoughtTogether({
    searchClient,
    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 algoliasearch from 'algoliasearch';

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

const searchClient = algoliasearch(appId, apiKey);

function App({ currentObjectID }) {
  // ...
  const { recommendations } = useRecommendations({
    model: 'related-products',
    searchClient,
    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

searchClient

SearchClient | 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.

fallbackFilters

list of strings

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

searchParameters

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.3 (2021-06-14)

This release renames the packages:

• @algolia/ui-components-horizontal-slider-js
• @algolia/ui-components-horizontal-slider-react
• @algolia/ui-components-horizontal-slider-theme
• @algolia/ui-components-horizontal-slider-vdom
• @algolia/recommend-core
• @algolia/recommend-js
• @algolia/recommend-react
• @algolia/recommend-vdom

Features

• rename packages to Recommend (#33) (4612d0d)
• horizontal-slider: change renderer implementation to VDOM (#28) (e297a92)
• recommendations: change renderer implementation to VDOM (#27) (29edf36)