React UI Reference

The Depict UI React SDK enables seamless integration of Depict Search UI into your React web applications. With our developer-friendly components and wrappers, you can effortlessly add powerful search functionality to your eCommerce website.

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

The Depict search modal is the component that captures users’ queries in a text field. This component is triggered when either of the following events occurs:

The open callback function, returned by the useDepictSearchModal hook, is called.
When a click event occurs on the DepictSearchField component. In both cases, you can align the top of the modal to the top of another DOM element by using the alignerRef property.

📘 Modal alignment on smaller screens

When the viewport height is below 900px, the search modal will overlook the element reference passed to the alignerRef property and center the search modal to the top of the viewport.

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"
    search={{
      searchPagePath: "SEARCH_RESULTS_PAGE_PATH",
    }}
  >
    <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

The translations for the UI
The locale to request from backend
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.

object

Configuration object lets you customize your website’s search parameters, see further below.

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 search property on the DepictProvider wrapper is a configuration object that allows you to modify search parameters on your website. Use the config to tailor your search URL and behavior. The following table shows the search object’s configuration properties:

searchPagePath

string

default:"undefined"

The unique URL path to your website’s search page.

urlParamName

string

default:"search_query"

The URL parameter (or query string) for each search on your website.

enableCategorySuggestions

boolean

default:"false"

Whether to enable showing product listing pages matching the search query, in the search modal and search page.

enableContentSearch

boolean

default:"false"

Enable or disable content search (seeing articles, FAQ, blog posts, etc in search results).

The search modal component to use. You can switch between the classic and the new search modal. See here for screenshots. Provide one of the components here that you can import from the same package as the one you’re using to see this message (SearchModalV2 or ClassicSearchModal). You also need to reflect the choice in SCSS, example:

@use "@depict-ai/js-ui" as plp-styling with (
  $search-modal-layout: "v2" // or "classic"
);

The default is SearchModalV2. That means that ClassicSearchModal can get tree-shaken if you use v2 but not vice-versa. To force SearchModalV2 from being tree-shaken, set process.env.NO_SEARCH_MODAL_DEFAULT to “true”.

The `useSearchField` hook

Use the useSearchField hook to render a search field on your site. The destructured value is the SearchField component to be nested within your application. The SearchField component displays a search field that opens the Depict search modal.

SearchField with the modal aligned to the search field

TypeScript

import React from "react";
import { useSearchField } from "@depict-ai/react-ui";

const App = () => {
  const { SearchField } = useSearchField();

  return (
    <div>
      <SearchField />
    </div>
  );
};

SearchField with the modal aligned to another DOM element

TypeScript

import React from "react";
import { ComponentAligner, useSearchField } from "@depict-ai/react-ui";

const App = () => {
  const ref = useRef(null);
  const { SearchField } = useSearchField({
    alignerRef: ref,
  });

  return (
    <div>
      <ComponentAligner ref={ref} />
      <SearchField />
    </div>
  );
};

The following table shows the useSearchField hook’s configuration properties, their types, and descriptions:

alignerRef

React.RefObject

default:"undefined"

This is the ref of the element in the DOM to which you intend to align the resulting modal.When not provided, the modal aligns on the SearchField itself.

stateKey

string | undefined

When using multiple search instances on the same page, you need to set a unique stateKey for each one. When only using one instance, leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a SearchField with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the “default” instance will be used.

The `useSearchModal` hook

Use the useSearchModal hook in place of the SearchField component to dynamically open the search modal.

TypeScript

const { open } = useSearchModal({
  location: "centered",
});

The destructured value is a function that opens the modal in response to user events. For example:

TypeScript

return (
  <div>
    <button onClick={open}>Search</button>
  </div>
);

The following table shows the useSearchModal hook’s configuration properties, their types, and descriptions:

location

centered | aligned

default:"centered"

This represents the location on the DOM to which the modal should be aligned. Set this value to aligned to align the modal to an element on your website.

alignerRef

React.RefObject

This is the ref of the element in the DOM to which you intend to align the modal.

stateKey

string | undefined

When using multiple search instances on the same page, you need to set a unique stateKey for each one. When only using one instance, leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the “default” instance will be used.

The `SearchPage` component

The SearchPage component acts as the search results page on your site. It is responsible for rendering results from each search.

TypeScript

import SearchProductCard from "./SearchProductCard.js";

export default function SearchResultsPage() {
  return (
    <SearchPage
      productCard={SearchProductCard}
      columnsAtSize={[[1, 500], [2, 1000], [3]]}
    />
  );
}

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

productCard

React.Element<typeof Component>

The React component to use for rendering products.

columnsAtSize

array

default:"[[2,901],[3,1024],[4]]"

Used to customize breakpoints on the search results page. Handles the number of product card columns displayed at each screen size.

gridSpacing

string | { horizontal: string; vertical: string }

default:"2%"

The spacing between products.

includeInputField

boolean

default:"true"

Visibility of the search input field that’s part of SearchPage.

stateKey

string | undefined

When using multiple search instances on the same page, you need to set a unique stateKey for each one. When only using one instance, leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the “default” instance will be used.

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.

ReactContentBlock type definition

/**
 * 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;
};

On this page

The Depict search modal
React component API
The DepictProvider component
The useSearchField hook
The useSearchModal hook
The SearchPage component

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

The Depict search modal is the component that captures users’ queries in a text field. This component is triggered when either of the following events occurs:

The open callback function, returned by the useDepictSearchModal hook, is called.
When a click event occurs on the DepictSearchField component. In both cases, you can align the top of the modal to the top of another DOM element by using the alignerRef property.

📘 Modal alignment on smaller screens

When the viewport height is below 900px, the search modal will overlook the element reference passed to the alignerRef property and center the search modal to the top of the viewport.

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"
    search={{
      searchPagePath: "SEARCH_RESULTS_PAGE_PATH",
    }}
  >
    <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

The translations for the UI
The locale to request from backend
The currency formatting used on the frontend

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.

object

Configuration object lets you customize your website’s search parameters, see further below.

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

searchPagePath

string

default:"undefined"

The unique URL path to your website’s search page.

urlParamName

string

default:"search_query"

The URL parameter (or query string) for each search on your website.

enableCategorySuggestions

boolean

default:"false"

Whether to enable showing product listing pages matching the search query, in the search modal and search page.

enableContentSearch

boolean

default:"false"

Enable or disable content search (seeing articles, FAQ, blog posts, etc in search results).

@use "@depict-ai/js-ui" as plp-styling with (
  $search-modal-layout: "v2" // or "classic"
);

The `useSearchField` hook

SearchField with the modal aligned to the search field

TypeScript

import React from "react";
import { useSearchField } from "@depict-ai/react-ui";

const App = () => {
  const { SearchField } = useSearchField();

  return (
    <div>
      <SearchField />
    </div>
  );
};

SearchField with the modal aligned to another DOM element

TypeScript

import React from "react";
import { ComponentAligner, useSearchField } from "@depict-ai/react-ui";

const App = () => {
  const ref = useRef(null);
  const { SearchField } = useSearchField({
    alignerRef: ref,
  });

  return (
    <div>
      <ComponentAligner ref={ref} />
      <SearchField />
    </div>
  );
};

The following table shows the useSearchField hook’s configuration properties, their types, and descriptions:

alignerRef

React.RefObject

default:"undefined"

This is the ref of the element in the DOM to which you intend to align the resulting modal.When not provided, the modal aligns on the SearchField itself.

stateKey

string | undefined

The `useSearchModal` hook

Use the useSearchModal hook in place of the SearchField component to dynamically open the search modal.

TypeScript

const { open } = useSearchModal({
  location: "centered",
});

The destructured value is a function that opens the modal in response to user events. For example:

TypeScript

return (
  <div>
    <button onClick={open}>Search</button>
  </div>
);

The following table shows the useSearchModal hook’s configuration properties, their types, and descriptions:

location

centered | aligned

default:"centered"

This represents the location on the DOM to which the modal should be aligned. Set this value to aligned to align the modal to an element on your website.

alignerRef

React.RefObject

This is the ref of the element in the DOM to which you intend to align the modal.

stateKey

string | undefined

When using multiple search instances on the same page, you need to set a unique stateKey for each one. When only using one instance, leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the “default” instance will be used.

The `SearchPage` component

The SearchPage component acts as the search results page on your site. It is responsible for rendering results from each search.

TypeScript

import SearchProductCard from "./SearchProductCard.js";

export default function SearchResultsPage() {
  return (
    <SearchPage
      productCard={SearchProductCard}
      columnsAtSize={[[1, 500], [2, 1000], [3]]}
    />
  );
}

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

productCard

React.Element<typeof Component>

The React component to use for rendering products.

columnsAtSize

array

default:"[[2,901],[3,1024],[4]]"

Used to customize breakpoints on the search results page. Handles the number of product card columns displayed at each screen size.

gridSpacing

string | { horizontal: string; vertical: string }

default:"2%"

The spacing between products.

includeInputField

boolean

default:"true"

Visibility of the search input field that’s part of SearchPage.

stateKey

string | undefined

When using multiple search instances on the same page, you need to set a unique stateKey for each one. When only using one instance, leave this unset. We recommend using an incrementing number, such as “1”, “2”, “3”, etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the “default” instance will be used.

contentBlocksByRow

(undefined | ReactContentBlock)[]?

ReactContentBlock type definition

/**
 * 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;
};

On this page

The Depict search modal
React component API
The DepictProvider component
The useSearchField hook
The useSearchModal hook
The SearchPage component

React component API

The `DepictProvider` component

The `useSearchField` hook

The `useSearchModal` hook

The `SearchPage` component

Glossary

Shopify app

Data ingestion

Search

Product Listing Pages

Product Listing Pages and Search

Looks

Recommendations SDK

Tracking Product Interactions

HTTP API

React UI Reference

React component API

The `DepictProvider` component

The `useSearchField` hook

The `useSearchModal` hook

The `SearchPage` component

​The Depict search modal

​React component API

​The DepictProvider component

​The useSearchField hook

​The useSearchModal hook

​The SearchPage component

Glossary

Shopify app

Data ingestion

Search

Product Listing Pages

Product Listing Pages and Search

Looks

Recommendations SDK

Tracking Product Interactions

HTTP API

​The Depict search modal

​React component API

​The DepictProvider component

​The useSearchField hook

​The useSearchModal hook

​The SearchPage component

The Depict search modal

React component API

The `DepictProvider` component

The `useSearchField` hook

The `useSearchModal` hook

The `SearchPage` component

The Depict search modal

React component API

The `DepictProvider` component

The `useSearchField` hook

The `useSearchModal` hook

The `SearchPage` component