JavaScript SDK
Learn how to integrate Depict Category Page UI with our 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
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.

Highlighted: Breadcrumbs, enabling navigation to parent categories.
In this configuration, as part of CategoryPage
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.

Example of BreadCrumbs
positioned freely on the page
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.

Highlighted: QuickLinks
, enabling navigation between categories.
In this configuration, as part of CategoryPage
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.

Example of QuickLinks
positioned freely on the page
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:

Example usage of CategoryTitle
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:

Example of the category_title_plugin
property set to CategoryTitle
.
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
// ...
});

embedded_number_of_products
being used as category_title_plugin

Showcasing how embedded_number_of_products
responsively moves the number of products between the filter buttons if the chosen filtering and localisation permits, making more of the product fit into the screen without scrolling.
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 theCategoryPage
component. This allows theCategoryPage
component to give a UI experience adapted to people switching between categories when they do. It also improves performance.
Updated about 1 month ago