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
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 theuseDepictSearchModal 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 thealignerRef
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
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:
This is the unique merchant identifier given by Depict.
This specifies the market identifier.
Configuration object lets you customize your website’s search parameters.
This handles the Depict Search UI translations and price formatting, gotten from the Depict locale object.
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
Identifies a logged in user, if applicable
A <string, string>
map of custom metadata to include in API requests to Depict
A function that can be used to create page_urls inside of the displays and
otherwise modify all displays before the productCard
’s are rendered. 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:
The unique URL path to your website’s search page.
The URL parameter (or query string) for each search on your website.
To enable or disable category suggestions.
Enable or disable content search (seeing articles, FAQ, blog posts, etc in search results).
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
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
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:
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.
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.
const { open } = useSearchModal({
location: "centered",
});
The destructured value is a function that opens the modal in response to user events. For example:
return (
<div>
<button onClick={open}>Search</button>
</div>
);
The following table shows the useSearchModal
hook’s configuration properties, their types, and descriptions:
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.
This is the ref of the element in the DOM to which you intend to align the modal.
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.
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:
The React component to use for rendering products.
Used to customize breakpoints on the search results page. Handles the number of product card columns displayed at each screen size.
The spacing between products.
Visibility of the search input field that’s part of SearchPage.
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.
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.
Was this page helpful?