JavaScript SDK

Use our JavaScript SDK to integrate a Depict Category Page UI into your website. The JavaScript SDK consists of the following parts:

• Getting started
  • Installation
  • Initialization and configuration
• Create a category page
• BreadCrumbs
• QuickLinks (optional)
• Category title (plugin)

Getting started

This quickstart shows how to set up and configure the Depict Category Page UI JavaScript SDK.

Installation

Install Depict Category Page UI package using NPM or Yarn:

npm i @depict-ai/ui

yarn add @depict-ai/ui

Initialization and configuration

Initialize Depict Category Page UI by creating a new instance of the DepictCategory object. This class holds the configuration for product categories.
Before initializing Depict Category Page UI, you must create a Depict API instance for your application. This acts as a wrapper to access Depict's API endpoints. To create the Depict API instance:

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

const api = new DepictAPI();

📘

Use the same DepictAPI instance created for Depict Search UI if applicable.

Next, import the DepictCategory object from the JavaScript SDK and create a new instance with the following configuration:

import { DepictAPI, DepictCategory } from "@depict-ai/ui";

const api = new DepictAPI();

const depictCategory = new DepictCategory({
  api,
  market: "MARKET_IDENTIFIER",
  merchant: "MERCHANT_ID",
  localization: {
    ...english_search_translations, 
    price_formatting_: {
      pre_: "", 
      post_: "EUR", 
      decimal_places_delimiter_: ".", 
      thousands_delimiter_: " ",
      places_after_comma_: "auto", 
    }
  },
   // Below is optional, for SPAs
  on_navigation: href => next.router.push(href) // function that will be used to navigate the page for SPAs
});

You can also update properties on the DepictCategory object by assigning new values to these properties as shown:

import { DepictAPI, DepictCategory } from "@depict-ai/ui";

const api = new DepictAPI();

const depictCategory = new DepictCategory({
  api,
  market: "MERCHANT_ID",
  merchant: "MARKET_IDENTIFIER",
});

depictCategory.market = "NEW_MARKET_ID"
depictCategory.merchant = "NEW_MERCHANT_IDENFIFIER"

📘

Ensure you create only one DepictCategory instance in your entire application.

Create a category page

The CategoryPage component renders the main category page based on the configuration in DepictCategory.
In its minimal configuration, the system displays the number of items within a specific category and possesses advanced filtering and sorting capabilities. The products within the selected category are also listed. The CategoryPage also includes optional BreadCrumbs and QuickLinks properties by default. However, you can remove these elements by setting their respective values to false.

To create a category page, you must provide the SDK with the category currently being viewed by the user. To do this, update the category_id property on the depictCategory object every time the category identifier changes.

depictCategory.category_id = "t-shirts";

Then, to create a category page:

import { CategoryPage, CategoryTitle } from "@depict-ai/ui";

const categoryPage = CategoryPage({ 
  search_state,
  show_breadcrumbs: true, 
  show_quicklinks: true, 
  category_title_plugin: CategoryTitle, 
    cols_at_size: [ 
      [2, 650],
      [3, 950],
    [4, 1650],
    [5]
  ] as const,
  grid_spacing: "2%",
  product_card_template, 
});

The CategoryPage object returns an array of Nodes that contains the data for the currently viewed category.

BreadCrumbs

Breadcrumbs refer to the "trail" in the header of a category page. They allow you to navigate to categories above the current category in the category tree.

The CategoryPage object incorporates breadcrumbs by default. However, it is possible to disable this feature and utilize the BreadCrumbs component. This is preferable if you wish to have the BreadCrumbs component outside your page's CategoryPage component.

To use the BreadCrumbs component:

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

const breadCrumbs = BreadCrumbs({ depictCategory });

This returns an HTML element you can insert anywhere on your DOM tree.

QuickLinks (optional)

The QuickLinks component lets the user go sideways and downwards in the category tree. It shows sibling categories and navigates the page to another category when a user clicks the link.

As with BreadCrumbs, QuickLinks are integrated into the CategoryPage object per default. However, you can disable this feature and utilize the QuickLinks component. This is preferable if you wish to have the QuickLinks component outside your page's CategoryPage component.

To utilize the QuickLinks component:

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

const quickLinks = QuickLinks({ depictCategory }); 

This also returns an HTML component you can insert anywhere in your DOM tree.

Category title (plugin)

The SDK provides two configurations for titles on the Category Page for better customization. When creating an instance of the CategoryPage object, you must decide if it should contain the category title or if it should contain just the number of products. The Depict Category Page UI SDK provides 2 "plugins" to address this.
The following screenshot showcase the CategoryTitle plugin in use:

The default option—CategoryTitle— puts the category title as text directly above the product cards containing the current category's name and the number of products in the current category. This format is preferred if you don't require additional content before the product cards. To use the CategoryTitle, instantiate the CategoryPage object as shown:

import { CategoryPage, CategoryTitle } from "@depict-ai/ui";

const categoryPage = CategoryPage({
  category_title_plugin: CategoryTitle
  // ...
});

This renders the category title as a header within the CategoryPage component as shown:

Alternatively, it is possible to omit the category title as a heading and only display the number of products within the current category. This option is ideal for merchants who prefer to create their category titles. To do this, assign the category_title_plugin the following value:

import { CategoryPage, embedded_number_of_products } from "@depict-ai/ui";

const categoryPage = CategoryPage({
  category_title_plugin: embedded_number_of_products
  // ...
});

❗️

Pitfall

If your application is an SPA, ensure that your SPA framework does not re-render the CategoryPage component when going from one category page to another. A re-rendering is only necessary when going from a page that is not a category page to a category page.

Hence, always re-use the CategoryPage component that you rendered for a previous page if that also had the CategoryPage component. This allows the CategoryPage component to give a UI experience adapted to people switching between categories when they do. It also improves performance.