The Depict Category Page UI React SDK enables seamless integration of Depict Category Page UI into your React web applications. With our developer-friendly components and wrappers, you can effortlessly render all product categories to your eCommerce website.

Please find the guide on how to integrate with depict if you’re using react here.

​
React component API

The SDK is pre-built with React components and wrappers, making it a perfect fit for React.js and Next.js web applications. The following sections describe these components and their configuration.

​
The DepictProvider component

The DepictProvider is a wrapper component for the root component of your entire application. It provides configuration to all Depict UI components beneath it.

TypeScript
return (
  <DepictProvider merchant="MERCHANT_ID" market="MARKET_IDENTIFIER">
    <div className="App">...</div>
  </DepictProvider>
);

The following table shows all DepictProvider configuration properties, their types, and descriptions:

​
merchant
string

This is the unique merchant identifier given by Depict.

​
market
string

This specifies the market identifier.

​
locale
Locale

Locale object imported from @depict-ai/react-ui/locales. Determines

  1. The translations for the UI
  2. The locale to request from backend
  3. The currency formatting used on the frontend

You have to check demo.depict.ai to see which locales the Depict backend accepts for your specific merchant. The different objects exported from @depict-ai/js-ui/locales have a backend_locale_ property equivalent to their name, so either import the locale with the correct name (recommended) or just set the backend_locale_ property to the correct value.

You can modify or create your own locale object as long as it’s the same format as the ones in @depict-ai/js-ui/locales.

​
search?
object

Configuration object lets you customize your website’s search parameters.

​
navigateFunction?
(href: string) => void

This function will be used internally by our components to navigate between Depict Search UI pages.This prop is required in all applications that don’t use Next.JS

​
sessionId?
string

Optionally you can override the default session id used for personalization here. This is the ID that will be used to tie together the different tracking events for a user.

​
metaData?
object

A <string, string> map of custom metadata to include in API requests to Depict

​
displayTransformers?
DisplayTransformers

DisplayTransformers are functions that take in a list of categories, content search results or products and then can transform or enrich the data for each category, content search result or product card in a batched way. See Creating page URLs and enriching product data.

​
The CategoryPage component

The CategoryPage component renders your site’s different product category pages.

TypeScript
return (
  <div>
    <CategoryPage
      categoryId="CATEGORY_IDENTIFIER"
      productCard={ProductCard}
      columnsAtSize={[[4], [3, 1024], [2, 901]]}
      categoryTitlePlugin={EmbeddedNumProducts}
    />
  </div>
);

The following table shows all CategoryPage configuration properties, their types, and descriptions:

​
listingQuery
({ type?: "listingId" | "externalId", id: string })?

The unique identifier for the current listing page that will be sent to depict to get the products to display. type can be "listingId" or "externalId"..

​
categoryTitlePlugin
(typeof CategoryTitle | typeof EmbeddedNumProducts)?
default:"CategoryTitle"

Accepts one of two “plugins” that determines the layout of your category page. The default value—CategoryTitle—displays the current category title above the product cards. Alternatively, you can opt not to show the category title above the product card by using the EmbeddedNumProducts function imported from the @depict-ai/react-ui SDK. This option is ideal for merchants who prefer to create their titles on the category page. If the latter, the SDK will attempt to position it between the sort and filter button on smaller screens to save space.

​
productCard
React.Element<typeof Component

Your custom ProductCard component that receives and renders your category data

​
columnsAtSize
array?
default:"[[2,901],[3,1024],[4]]"

Used to customize breakpoints on category pages. Handles the number of product card columns displayed at each screen size. Example: [[2, 901], [3, 1024], [4]] means 2 columns at sizes up to 901px, 3 columns at sizes up to 1024px and after that 4 columns at any viewport size.

​
gridSpacing
(string | { horizontal: string; vertical: string })?
default:"2%"

The spacing between products.

​
showBreadcrumbs
boolean?
default:"true"

Handles whether or not to show the default breadcrumbs on the category page. If layout is set to "slider" or "slider-without-filters" this will be set to false by default

​
showQuicklinks
boolean?
default:"true"

Handles whether or not to show the default quick links on the category page. If layout is set to "slider" or "slider-without-filters" this will be set to false by default

​
layout
("grid" | "slider" | "slider-without-filters")?
default:"\"grid\""

The layout used for listing the products.

  1. "grid" is the default and shows the products in a grid
  2. "slider" shows the products in a slider and has default false for showBreadcrumbs and showQuicklinks
  3. "slider-without-filters" is the same as "slider" but does also not render any sorting or filter buttons
​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.

​
contentBlocksByRow
(undefined | ReactContentBlock)[]?

A sparse array containing content blocks to show (or an empty slot or undefined if there’s no block at that index). See ReactContentBlock for how a content block looks like. The index is the row where the content block should be shown.

​
The BreadCrumbs component

Breadcrumb navigation helps users know their location in the category tree by providing a trail back to the root category. By default, the CategoryPage component contains breadcrumb navigation. You can disable its default breadcrumb navigation by setting the showBreadcrumbs property to false. To add a custom breadcrumb navigation, import the BreadCrumbs component from the SDK and nest it in the desired location on your DOM tree.

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

const CategoryMain = () => {
  return (
    <>
      <BreadCrumbs />
    </>
  );
};

The following table shows all BreadCrumbs configuration properties, their types, and descriptions:

​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.

The QuickLinks component shows all available product categories in a carousel for easy navigation. By default, the CategoryPage component contains quick link navigation. You can disable its default quick link navigation by setting the showQuicklinks property to false. To add a custom quick link navigation, import the QuickLinks component from the SDK and nest it in the desired location on your DOM tree.

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

const Carousel = () => {
  return (
    <>
      <QuickLinks />
    </>
  );
};

The following table shows all QuickLinks configuration properties, their types, and descriptions:

​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.

The Depict Category Page UI React SDK enables seamless integration of Depict Category Page UI into your React web applications. With our developer-friendly components and wrappers, you can effortlessly render all product categories to your eCommerce website.

Please find the guide on how to integrate with depict if you’re using react here.

​
React component API

The SDK is pre-built with React components and wrappers, making it a perfect fit for React.js and Next.js web applications. The following sections describe these components and their configuration.

​
The DepictProvider component

The DepictProvider is a wrapper component for the root component of your entire application. It provides configuration to all Depict UI components beneath it.

TypeScript
return (
  <DepictProvider merchant="MERCHANT_ID" market="MARKET_IDENTIFIER">
    <div className="App">...</div>
  </DepictProvider>
);

The following table shows all DepictProvider configuration properties, their types, and descriptions:

​
merchant
string

This is the unique merchant identifier given by Depict.

​
market
string

This specifies the market identifier.

​
locale
Locale

Locale object imported from @depict-ai/react-ui/locales. Determines

  1. The translations for the UI
  2. The locale to request from backend
  3. The currency formatting used on the frontend

You have to check demo.depict.ai to see which locales the Depict backend accepts for your specific merchant. The different objects exported from @depict-ai/js-ui/locales have a backend_locale_ property equivalent to their name, so either import the locale with the correct name (recommended) or just set the backend_locale_ property to the correct value.

You can modify or create your own locale object as long as it’s the same format as the ones in @depict-ai/js-ui/locales.

​
search?
object

Configuration object lets you customize your website’s search parameters.

​
navigateFunction?
(href: string) => void

This function will be used internally by our components to navigate between Depict Search UI pages.This prop is required in all applications that don’t use Next.JS

​
sessionId?
string

Optionally you can override the default session id used for personalization here. This is the ID that will be used to tie together the different tracking events for a user.

​
metaData?
object

A <string, string> map of custom metadata to include in API requests to Depict

​
displayTransformers?
DisplayTransformers

DisplayTransformers are functions that take in a list of categories, content search results or products and then can transform or enrich the data for each category, content search result or product card in a batched way. See Creating page URLs and enriching product data.

​
The CategoryPage component

The CategoryPage component renders your site’s different product category pages.

TypeScript
return (
  <div>
    <CategoryPage
      categoryId="CATEGORY_IDENTIFIER"
      productCard={ProductCard}
      columnsAtSize={[[4], [3, 1024], [2, 901]]}
      categoryTitlePlugin={EmbeddedNumProducts}
    />
  </div>
);

The following table shows all CategoryPage configuration properties, their types, and descriptions:

​
listingQuery
({ type?: "listingId" | "externalId", id: string })?

The unique identifier for the current listing page that will be sent to depict to get the products to display. type can be "listingId" or "externalId"..

​
categoryTitlePlugin
(typeof CategoryTitle | typeof EmbeddedNumProducts)?
default:"CategoryTitle"

Accepts one of two “plugins” that determines the layout of your category page. The default value—CategoryTitle—displays the current category title above the product cards. Alternatively, you can opt not to show the category title above the product card by using the EmbeddedNumProducts function imported from the @depict-ai/react-ui SDK. This option is ideal for merchants who prefer to create their titles on the category page. If the latter, the SDK will attempt to position it between the sort and filter button on smaller screens to save space.

​
productCard
React.Element<typeof Component

Your custom ProductCard component that receives and renders your category data

​
columnsAtSize
array?
default:"[[2,901],[3,1024],[4]]"

Used to customize breakpoints on category pages. Handles the number of product card columns displayed at each screen size. Example: [[2, 901], [3, 1024], [4]] means 2 columns at sizes up to 901px, 3 columns at sizes up to 1024px and after that 4 columns at any viewport size.

​
gridSpacing
(string | { horizontal: string; vertical: string })?
default:"2%"

The spacing between products.

​
showBreadcrumbs
boolean?
default:"true"

Handles whether or not to show the default breadcrumbs on the category page. If layout is set to "slider" or "slider-without-filters" this will be set to false by default

​
showQuicklinks
boolean?
default:"true"

Handles whether or not to show the default quick links on the category page. If layout is set to "slider" or "slider-without-filters" this will be set to false by default

​
layout
("grid" | "slider" | "slider-without-filters")?
default:"\"grid\""

The layout used for listing the products.

  1. "grid" is the default and shows the products in a grid
  2. "slider" shows the products in a slider and has default false for showBreadcrumbs and showQuicklinks
  3. "slider-without-filters" is the same as "slider" but does also not render any sorting or filter buttons
​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.

​
contentBlocksByRow
(undefined | ReactContentBlock)[]?

A sparse array containing content blocks to show (or an empty slot or undefined if there’s no block at that index). See ReactContentBlock for how a content block looks like. The index is the row where the content block should be shown.

​
The BreadCrumbs component

Breadcrumb navigation helps users know their location in the category tree by providing a trail back to the root category. By default, the CategoryPage component contains breadcrumb navigation. You can disable its default breadcrumb navigation by setting the showBreadcrumbs property to false. To add a custom breadcrumb navigation, import the BreadCrumbs component from the SDK and nest it in the desired location on your DOM tree.

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

const CategoryMain = () => {
  return (
    <>
      <BreadCrumbs />
    </>
  );
};

The following table shows all BreadCrumbs configuration properties, their types, and descriptions:

​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.

The QuickLinks component shows all available product categories in a carousel for easy navigation. By default, the CategoryPage component contains quick link navigation. You can disable its default quick link navigation by setting the showQuicklinks property to false. To add a custom quick link navigation, import the QuickLinks component from the SDK and nest it in the desired location on your DOM tree.

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

const Carousel = () => {
  return (
    <>
      <QuickLinks />
    </>
  );
};

The following table shows all QuickLinks configuration properties, their types, and descriptions:

​
stateKey
string | undefined

When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one, otherwise leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.