Quickstart

Get started with Depict Search UI React SDK by installing the package and importing the components you want to use in your app. For a complete list of components and their configuration, see React SDK components.

Prerequisites

Before proceeding, ensure you have sent your product data to Depict for processing and analysis. If you haven't already, Sending Data to Depict.

Installation

The Depict UI React package is available in the NPM registry. To install:

npm install @depict-ai/react-ui

yarn add @depict-ai/react-ui

The DepictProvider configuration

Import the DepictProvider component from the installed package and use this component to wrap your entire application's component tree as shown:

import { DepictProvider } from "@depict-ai/react-ui";
import { en } from "@depict-ai/react-ui/locales";

function App() {
  return (
    <DepictProvider
      merchant="MERCHANT_ID"
      market="MARKET_IDENTIFIER"
      search={{
        searchPagePath: "/search",
      }}
      locale={en}
    >
      <div className="App">
        ...
      </div>
    </DepictProvider>
  );
}

export default App;

The locale property on the DepictProvider wrapper accepts a JavaScript object that handles UI translations and price formatting. Import any of our supported locales from the @depict-ai/react-ui/locales subpackage.

📘

The searchPagePath value must match the route path for your application's search page component.

Import styling

You can make use of our default styling by importing the SDK styling into your SCSS file as follows:

@use "@depict-ai/react-ui" as plp-styling;

@include plp-styling.default-theme("search");

This includes all the default styling for all Depict Search UI components. You can also customize components' styling to fit your website's specifications. For more information, see Modify and Customize Styling.

Add a search field or search modal

Use the useSearchField hook to add a search field on your site. Destructure the SearchField component from this hook and nest the component within your application as shown:

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

function Header() {
 const elementRef = useRef();
   
 const { SearchField } = useSearchField({
   alignerRef: elementRef,
 });
  
 return (
   <header>
     <div ref={elementRef} />
     <SearchField /> 
   </header>
  );
}

export default Header;

What if, instead of having a search field, the search modal is triggered when a user clicks a button?

Alternatively, you can use the useDepictSearchModal hook to open a search modal in response to user events.

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

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

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

By default, the useSearchModal hook centers the search modal to the top of the viewport. You can use the hook's location and alignerRef properties to align the modal to the top of a specific component on the DOM. To open an aligned search modal:

import { useSearchModal } from "@depict-ai/react-ui";
import { useRef } from "react";

const Nav = () => {
  const modalAlignmentRef = useRef();

  const { open } = useSearchModal({
    location: "aligned",
    alignerRef: modalAlignmentRef,
  });

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

Set up page routing

After setting up the search modal, you need to set up page routing to redirect users to different pages based on their search requests. The Depict Search UI React SDK supports the following routing:

• React Router.
• Next.js' built-in router.

The SDK supports page routing in Next.js applications without any extra configuration. However, React.js applications using other routing solutions must use the navigateFunction property on the DepictProvider wrapper to handle routing to search result pages as shown:

import { Routes, Route, useNavigate } from "react-router-dom";
import { DepictProvider } from "@depict-ai/react-ui";

function App() {
  const navigate = useNavigate();

  return (
    <DepictProvider
      merchant="MERCHANT_ID"
      market="MARKET_IDENTIFIER"
      navigateFunction={navigate}
      search={{
        searchPagePath: "/search",
      }}
    >
      <Routes>
        <Route path="/" exact element={<Home />} />
        <Route path="/search" element={<Search />} />
      </Routes>
    </DepictProvider>
  );
}

📘

If using another routing library, you can define your navigation function compatible with React Router's NavigateFunction type.

Set up your search results page

At the moment, attempting to search the website will return no results. You must set up and configure your search results page using the SearchPage component to render results from the search. Import the component from the Depict UI SDK and nest it into your application's search page component.

import { SearchPage } from "@depict-ai/react-ui";
import ProductCard from "./ProductCard";

function Search() {
  return (
    <div>
      <SearchPage
        productCard={ProductCard}
        columnsAtSize={[[1, 500], [2, 820], [3, 1000], [4]]}
      />
    </div>
  );
}

export default Search;

The productCard prop accepts your custom ProductCard component that receives and renders the data obtained from each search. Use the columnsAtSize prop to handle breakpoints on your search results page. It defines the number of product card columns displayed at each screen size.

To find out more about the Search UI SDK's components and hooks and their usage configurations, see React component API.

Debugging and Error reporting

The Depict React UI SDK monitors your application internally for error occurrence and automatically sends an event to Depict once this occurs. This reporting lets us quickly notice if something is broken in our SDK and offers insight into fixing bugs. This reporting is, however, suppressed by default on your browser. You can show these events to gain insights into the SDK's internals.

To view event logs from the SDK, run the following command in your browser console:

localStorage.debug = true

Similarly, you can disable sending these error reports to Depict by setting the value of the SENTRY environment variable to false, as shown:

REACT_APP_SENTRY=false

NEXT_PUBLIC_SENTRY=false