> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# React UI Reference

> Learn more about our React SDK, its components and configuration.

<Warning>
  This page does not apply to installs made in 2025 or later of the Depict Shopify apps
</Warning>

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-ui-guide/introduction).

## 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.

```tsx TypeScript theme={null}
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:

<ResponseField name="merchant" type="string">
  This is the unique merchant identifier given by Depict.
</ResponseField>

<ResponseField name="market" type="string">
  This specifies the market identifier.
</ResponseField>

<ResponseField name="locale" type="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](https://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`.
</ResponseField>

<ResponseField name="search?" type="object">
  Configuration object lets you customize your website's search parameters.
</ResponseField>

<ResponseField name="navigateFunction?" type="(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
</ResponseField>

<ResponseField name="sessionId?" type="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.
</ResponseField>

<ResponseField name="metaData?" type="object">
  A \<string, string> map of custom metadata to include in API requests to Depict
</ResponseField>

<ResponseField name="displayTransformers?" type="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](/reference/listings-search/display-transformers).
</ResponseField>

<ResponseField name="imageResizer?" type="(url: string, width: number) => string">
  Optional function to override the default image resizing CDN. When provided, this function
  is called with the original image URL and desired width, and should return the resized image URL.
  By default, Depict uses Cloudflare's image resizer for non-Shopify images, and Shopify's built-in
  resizer for Shopify CDN images.
</ResponseField>

### The `CategoryPage` component

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

```tsx TypeScript theme={null}
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:

<ResponseField name="listingQuery" type="({ type?: &#x22;listingId&#x22; | &#x22;externalId&#x22;, 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"`..

  * If `id` is `"listingId"`, it should be a uuid where Depict is the source of truth, you can get them here: [https://api.depict.ai/docs#tag/Listing/operation/Get\_Listings\_v3\_listings\_get](https://api.depict.ai/docs#tag/Listing/operation/Get_Listings_v3_listings_get).
  * If `id` is `"externalId"`, it should be the id of the product listing in your system - whatever was passed to Depict during data ingestion.
</ResponseField>

<ResponseField name="categoryTitlePlugin" type="(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.
</ResponseField>

<ResponseField name="productCard" type="React.Element<typeof Component">
  Your custom `ProductCard` component that receives and renders your category
  data
</ResponseField>

<ResponseField name="columnsAtSize" type="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.
</ResponseField>

<ResponseField name="gridSpacing" type="(string |  { horizontal: string; vertical: string })?" default="2%">
  The spacing between products.
</ResponseField>

<ResponseField name="showBreadcrumbs" type="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
</ResponseField>

<ResponseField name="showQuicklinks" type="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
</ResponseField>

<ResponseField name="layout" type="(&#x22;grid&#x22; | &#x22;slider&#x22; | &#x22;slider-without-filters&#x22;)?" default="&#x22;grid&#x22;">
  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
</ResponseField>

<ResponseField name="stateKey" type="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.
</ResponseField>

<ResponseField name="contentBlocksByRow" type="(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.

  <Accordion title={<><code>ReactContentBlock</code> type definition</>}>
    ```ts theme={null}
    /**
     * The interface for a content block.
     * Please make sure that you don't have content blocks overlap as that will cause undefined behavior.
     * The height of the content block will be the height of the tallest item in a row, so if there are no products in a row the content block needs to "bring its own height".
     * If you need to load any data in the content block, please make sure to return a placeholder while you're doing so (see `ImagePlaceholder`), to avoid layout shifts and ensure scroll restoration works correctly.
     *
     * - `spanColumns`: How many columns the block should span. This will be capped to the number of columns available.
     * - `spanRows`: How many rows the block should span.
     * - `position`: Where the block should be positioned. Can be `left`, `center` or `right`.
     * - `content`: The content to render in the block - please provide a React component.
     */
    export type ReactContentBlock = {
      spanColumns: number;
      spanRows: number;
      position: "left" | "center" | "right";
      content: React.FC;
    };
    ```
  </Accordion>
</ResponseField>

### 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 tsx theme={null}
import { BreadCrumbs } from "@depict-ai/react-ui";

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

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

<ResponseField name="stateKey" type="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.
</ResponseField>

### The `QuickLinks` component

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 tsx theme={null}
import { QuickLinks } from "@depict-ai/react-ui";

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

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

<ResponseField name="stateKey" type="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.
</ResponseField>