Use our JavaScript UI SDK to integrate a Depict Search UI into your website.

Full example

Installation

Install @depict-ai/js-ui using NPM or Yarn:

npm i @depict-ai/js-ui

yarn add @depict-ai/js-ui

Usage

Configure the search provider

Configure the DepictSearchProvider as follows:

import { DepictSearchProvider } from "@depict-ai/js-ui";

const searchProvider = new DepictSearchProvider({
  market: "MARKET_IDENTIFIER",
  merchant: "MERCHANT_ID",
  searchPagePath: "PATH_TO_SEARCH_PAGE",
});

DepictSearchProvider's arguments are:

Property	Description	Required	Default
market	The market to use for the search.	Yes	-
merchant	The merchant to use for the search.	Yes	-
searchPagePath	The path to the search page.	Yes	-

Create the product card

Create your own product card component. The product card must be a function that takes a Display and that returns an HTMLElement (or an array of HTMLElement).
The Display properties depend on what Depict has configured for you. If you need help, please contact us.

export interface Display {
  product_id: string;
  image_url: string;
  sale_price: number;
  title: string;
  page_url: string;
  original_price: number;
  recommendation_id: string;
}

You can use the ImagePlaceholder component to display a placeholder image while the product image is loading.
You can use the TextPlaceholder component to display a placeholder text while the product title or price is loading.

import { Display } from "./display";
import { ImagePlaceholder, TextPlaceholder } from "@depict-ai/js-ui";

const img_aspect_ratio = 1.5;

export function productCard(display: Display | null) {
  const linkUrl = display ? `/pdp.html?product-id=${display.product_id}` : "#";

  let imgContainer: string;
  if (display) {
    const imgContainerStyle = `position:relative;width:100%;padding-bottom:${
      (1 / img_aspect_ratio) * 100
    }%`;
    const imgEl = `<img src="${display.image_url}" alt="" class="product-img depict-img-mod" loading="lazy" />`;
    imgContainer = `<div style="${imgContainerStyle}">${imgEl}</div>`;
  } else {
    imgContainer = ImagePlaceholder({
      aspectRatio: img_aspect_ratio,
    }).outerHTML;
  }

  const titleEl =
    display?.title ||
    TextPlaceholder({ height: "1em", width: "20ch" }).outerHTML;
  const priceEl =
    display?.sale_price ||
    TextPlaceholder({ height: "1em", width: "4ch" }).outerHTML;

  const html = `
    <div class="product-card">
      <a href="${linkUrl}">
        ${imgContainer}
        <span class="text-container">
          <span class="title">${titleEl}</span>
          <span class="price">${priceEl}</span>
        </span>
      </a>
    </div>
  `;

  const element = document.createElement("div");
  element.innerHTML = html;

  return element;
}

Configure the search page

Configure the SearchPage component as follows:

import { SearchPage } from "@depict-ai/js-ui";

const searchPage = SearchPage<Display>({
  searchProvider,
  productCard,
});

SearchPage's arguments are:

Property	Description	Required	Default
searchProvider	The `DepictSearchProvider` previously configured	Yes	-
productCard	The product card component to use.	Yes	-

Set up the PageReplacer

You want to set up the PageReplacer component so that you enjoy the benefits of client-side routing (instead of reloading the whole page on every navigation).

import { SetupPageReplacer } from "@depict-ai/js-ui";

SetupPageReplacer({
  isPageToReplace: (url) => url.pathname === "PATH_TO_SEARCH_PAGE",
  selectorToReplace: `.replace-for-depict`,
  renderContent: () => searchPage,
});

SetupPageReplacer's arguments are:

Property	Description	Required	Default
isPageToReplace	A function that returns true if the URL should be replaced by the search UI.	Yes	-
selectorToReplace	The selector of the element to replace.	Yes	-
renderContent	A function that returns the element(s) replacing the "page" when `isPageToReplace` returns `true`.	Yes	-

Set up the search field

You now need to hook the SearchField component to one of the elements of your page. In order to do that, you can leverage the onExistsObserver function we provide:

import { SearchField, onExistsObserver } from "@depict-ai/js-ui";

onExistsObserver(".search-field-wrapper", (element) =>
  element.append(SearchField({ searchProvider }))
);

onExistsObserver's arguments are:

Property	Description	Required	Default
selector	The selector of the DOM element you want to observe	Yes	-
callback	The callback to call when the element comes to existence	Yes	-

SearchField's arguments are:

Property	Description	Required	Default
searchProvider	The `DepictSearchProvider` previously configured	Yes	-