> ## 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.
# JavaScript UI Reference
This page does not apply to installs made in 2025 or later of the Depict Shopify apps
Use our JavaScript UI SDK to integrate a Depict Search UI into your website.
## Full example
## DepictSearchProvider class
The `DepictSearchProvider` class is what ties together all the search configuration for the different components. It is used to open the search modal.
If you want to dynamically change some properties, for example the market, please let us know and we'll help you out.
Example:
```ts theme={null}
import { DepictSearchProvider } from "@depict-ai/js-ui";
import { en } from "@depict-ai/js-ui/locales";
import { YourDisplay } from "./display-types.ts";
const searchProvider = new DepictSearchProvider({
merchant: "MERCHANT_ID",
market: "MARKET",
searchPagePath: "PATH_TO_SEARCH_PAGE",
locale: en,
});
```
The following table shows the `DepictSearchProvider`'s constructor properties, their types, and descriptions:
The merchant to use for the search.
The market to use for the search.
Locale object imported from `@depict-ai/js-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`.
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.
Custom metadata to be sent with each request to the Depict API. Only necessary
if specifically instructed by Depict.
A unique key for each instance, so that the state of each instance is kept
separate.
The path to the search page.
The name of the url parameter that will be used for the search query.
Whether to enable showing product listing pages matching the search query, in the search modal and search page.
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](/js-ui-guide/search/overview#2-the-search-modal-opens-this-is-what-the-user-sees-while-typing-a-query) 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:
```scss theme={null}
@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".
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).
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.
The following table shows methods of the `DepictSearchProvider` class:
A function used to open the search modal. `alignerElement` is an element the
SearchModal should align too.
A function used to fetch search results. `displayTransformers` will be ran on the
results before them being returned.
Generics:
* `OriginalDisplay`: This generic represents the original display type that extends the `Display` type. Provide a type of your display here (e.g. `YourDisplay`). Ask Depict for the type of your display.
* `OutputDisplay`: This generic represents the output display type (of the specified displayTransformer) that extends either the `ModernDisplay` type or `never`. Unelss specified, it is determined based on `OriginalDisplay`. If `OriginalDisplay` extends `ModernDisplay`, then `OutputDisplay` will be `ModernDisplayWithPageUrl`, otherwise it will be `never`.
## SearchPage function
The component displaying the search results page. See [screenshot](/js-ui-guide/search/overview#3-the-user-submits-a-query-and-goes-to-a-new-url-like-search).
The following table shows the `SearchPage`'s configuration properties, their types, and descriptions:
The search provider instance.
Whether to show the search input field in the search page.
The spacing between products.
How many columns to show at each media size. For 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.
The product card function to use for rendering products.
Can be used to know when the search query is changed and update other content
on the page accordingly. Will be called when the SearchPage is created, every
time the query changes and when the SearchPage is destroyed. When
newQuery is undefined it means the search page has been closed/left.
Function returned by contentBlockStore. See
[contentBlockStore](/reference/listings-search/js-ui#contentblockstore-function).
## SearchField function
{
// In prod, they have some zoom thing which breaks aspectRatio, work around that. Unfortunately this is not in the SSR'd output so there's still some CLS.
const direct_parent = element?.parentElement;
if (direct_parent?.matches?.("[data-rmiz-content]")) {
Object.assign(direct_parent.style, {
width: "100%",
display: "flex",
justifyContent: "center",
alignItems: "center",
});
}
const parents_parent = direct_parent?.parentElement;
if (parents_parent?.matches?.("[aria-owns^='rmiz-modal']")) {
parents_parent.style.width = "100%";
}
}}
data-og-width="1083"
width="1083"
data-og-height="81"
height="81"
data-path="images/search_field.svg"
data-optimize="true"
data-opv="3"
srcset="https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=280&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=d00f3c969ea031cf55396d60f9441a44 280w, https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=560&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=9f8774df7157002b8a3039fd112fb9c5 560w, https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=840&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=d7ddfab7a7db3b62a7e2d899d685334b 840w, https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=1100&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=0ad7efcd50d841ce18b9d31d122e7ada 1100w, https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=1650&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=24213a586dcbeb045c2b9ab994cc3146 1650w, https://mintcdn.com/depictai/oqYy6W_ukzaDVZL8/images/search_field.svg?w=2500&fit=max&auto=format&n=oqYy6W_ukzaDVZL8&q=85&s=d98ce7c6804559da9ffbfdc1819ff7ea 2500w"
/>
```ts theme={null}
import { SearchField, onExistsObserver } from "@depict-ai/js-ui";
onExistsObserver(".search-field-wrapper", (element) =>
element.append(SearchField({ searchProvider }))
);
```
The following table shows the `SearchField`'s configuration properties, their types, and descriptions:
The search provider instance.
A DOM element that the modal should be aligned to. If not provided, the modal
will be aligned to the search field itself.