GuidesAPI Reference

Javascript UI SDK Quickstart

Learn how to integrate Depict Search with our JavaScript UI SDK.

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

Full example


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

npm i @depict-ai/js-ui
yarn add @depict-ai/js-ui


Configure the search provider

Configure the DepictSearchProvider as follows:

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

const searchProvider = new DepictSearchProvider({
  merchant: "MERCHANT_ID",
  searchPagePath: "PATH_TO_SEARCH_PAGE",

DepictSearchProvider's arguments are:

marketThe market to use for the search.Yes-
merchantThe merchant to use for the search.Yes-
searchPagePathThe 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,

  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}">
        <span class="text-container">
          <span class="title">${titleEl}</span>
          <span class="price">${priceEl}</span>

  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>({

SearchPage's arguments are:

searchProviderThe DepictSearchProvider previously configuredYes-
productCardThe 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";

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

SetupPageReplacer's arguments are:

isPageToReplaceA function that returns true if the URL should be replaced by the search UI.Yes-
selectorToReplaceThe selector of the element to replace.Yes-
renderContentA 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:

selectorThe selector of the DOM element you want to observeYes-
callbackThe callback to call when the element comes to existenceYes-

SearchField's arguments are:

searchProviderThe DepictSearchProvider previously configuredYes-