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

# Search

> AI search in the Depict: Search & Merchandising app: how it reaches your theme, what the Search page lets you decide, and the theme-editor settings for how the search modal looks and behaves.

Search in the Depict: Search & Merchandising app is a search modal that opens
from an icon in your theme's header. It understands what shoppers mean
("something for a wedding in June"), ranks your catalog with the same signals
as your collections, and shows suggestions and top picks before the shopper
types.

Two places hold its configuration:

| Where | Decides | Who changes it |
| - | - | - |
| The **Search** page in the app | What search finds and ranks, what shoppers see before typing, what is hidden, and the search reports | You, in the app |
| Three app embeds and blocks in the **Shopify theme editor** | How the modal looks and behaves: template, layout, product cards, typography, colours, loading | You, in the theme editor, with Shopify's live preview |

<Note>
  Stores that still run the separate **Search by Depict** app find the same theme-editor settings documented under [Search by Depict](/shopify-search/introduction). The embeds are identical in both apps, only their names differ.
</Note>

## Before you start

Search has to be part of your plan; see [Plan](/shopify-lite/settings#your-plan).
With search in the plan, the Search page shows a setup guide that walks you
through preparing a preview theme, placing the search button and switching the
embeds on. [Theme setup](/shopify-lite/theme-setup) explains what each embed
and block does in your theme.

## The Search page

The Search page opens on an overview of the period: revenue via search,
orders, click-through, add to cart, searches that found nothing, and search
conversion, with the queries that need attention. The sections below it hold
the decisions:

| Section | Holds |
| - | - |
| **Overview** | The period's numbers and the query worklist. Synonyms, when enabled for your store. |
| **Queries** | Every query of the period with its results, clicks and revenue. |
| **Results & ranking** | Which fields search looks at, which filters it offers, search focus (precision against recall), sold-out products, boost & bury rules, and content pages (custom URLs that search can return). |
| **Shopper experience** | What shoppers see before typing: the top picks and the suggested queries, the AI suggestions' tone of voice and blocked terms, and translations of every label the modal shows. |

Changes on the Search page are live on your store as soon as they are saved.

## Theme-editor settings

The look and behaviour of the modal are set in the Shopify theme editor, so
you see every change in Shopify's live preview before saving. Open
**Shopify admin → Online Store → Themes → Customize**, then **App embeds**
(the puzzle-piece icon in the left sidebar). Two embeds carry the settings:

* **Depict Search Settings**: the template, the product grid and cards, the mobile layout, the headings before typing, and the header logo.
* **Depict Search Styling**: corner radius, typography, the search field's shape and shadows, the loading indicator, product card fonts and colours, dark theme, background colours and custom CSS.

The search button itself is an app block, **Depict Search Button**, placed in
your header; its own settings (icon, size, optional text) sit on the block.

### Depict Search Settings

To edit these settings: **Shopify admin → Online Store → Themes → Customize → App embeds**, then expand **Depict Search Settings**.

Global settings for how the search modal is laid out and behaves. These are configured once and apply to every search button on your store.

## Search template

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Search template | How search opens for shoppers. **Takeover** is the full-screen search. **Drawer** is a side panel from the header icon; the store stays visible. **Quick panel** is a centred panel over the store that grows when results arrive. Changing this changes the search experience for every shopper, so preview before saving. | Takeover, Drawer, Quick panel · default `Takeover` | Desktop (mobile is always full screen) |
| Drawer side | Drawer template only: the edge the panel slides in from. | Right, Left · default `Right` | Desktop |
| Drawer width | Drawer template only: the width of the panel on desktop. Results show two per row inside it. | `360`–`720` px (step 20) · default `560px` | Desktop |

## Product grid

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Show products in empty state on mobile | Show product recommendations immediately after opening search on mobile. Exposes more products, but can look crammed alongside the virtual keyboard. | On / Off · default `Off` | Mobile |
| Product card minimum size | Minimum width of each product card. The desktop grid fits as many cards as possible while keeping each at least this wide, automatically adjusting the number of columns. Takeover only: the drawer is fixed at two columns and the quick panel at three. | `100`–`450` px (step 10) · default `260px` | Desktop |
| Product grid gap | Spacing between product cards in the grid. | `0`–`100` px · default `20px` | Desktop & Mobile |

## Product card

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Product image aspect ratio | Aspect ratio for product card images. | Square (1:1), Portrait (3:4), Portrait (2:3), Portrait (4:5), Landscape (4:3), Landscape (3:2), Landscape (16:9) · default `Portrait (2:3)` | Desktop & Mobile |
| Show percentage off for on-sale products | Display the discount percentage on products that are on sale. | On / Off · default `Off` | Desktop & Mobile |
| Hide product title | Hide the product name on each card. | On / Off · default `Off` | Desktop & Mobile |
| Hide product price | Hide the price on each card. | On / Off · default `Off` | Desktop & Mobile |
| Red background on sale price | Highlight the price with a red background when the product is on sale. The corners follow the global **Border radius** (from the styling embed). | On / Off · default `Off` | Desktop & Mobile |

## Mobile layout

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Mobile search bar position | Where the search input sits on mobile: pinned to the bottom of the screen, or docked at the top under the header. | Bottom, Top · default `Bottom` | Mobile |
| Mobile submit button icon | Icon shown on the submit button next to the search field on mobile. | Chevron, Arrow up (send), Magnifier, Return arrow · default `Chevron` | Mobile |

## Search suggestions

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Custom search icon | Replaces the built-in magnifier shown in the search input field and in result-state messages (e.g. "No exact matches" and "no results"). Best with a simple, square, single-color icon. Leave empty for the default. | Image (optional) | Desktop & Mobile |
| Suggestions heading | Heading shown above the recommended searches in the suggestions dropdown (the default state, before the shopper types). Leave empty to hide it. | Text · default `Popular searches` | Desktop & Mobile |
| Top picks heading | Heading shown above the recommended products on the search start screen. Leave empty to use the default ("Our Top Picks", translated automatically per locale). How it is set (small caps or sentence case) is the **Section heading style** in the styling embed. | Text (optional) | Desktop & Mobile |

## Header logo

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Show logo in search header | Master switch for the logo in the top-left of the search modal. When on, your Shopify brand logo is used unless overridden below. | On / Off · default `On` | Desktop & Mobile |
| Logo type | Whether the header logo is an image or a text wordmark. | Image, Text · default `Image` | Desktop & Mobile |
| Logo text | Wordmark text shown when *Logo type* is **Text**. Defaults to your store name when empty. | Text (optional) | Desktop & Mobile |
| Text logo font size | Size for the text logo, e.g. `24px` or `2em`; a bare number is read as px. Leave empty to match the **Base font size** from the styling embed. | CSS font size (optional) | Desktop & Mobile |
| Logo image (desktop) | Header logo image on desktop when *Logo type* is **Image**. Falls back to your Shopify brand logo (Settings → Brand) when empty. | Image (optional) | Desktop |
| Logo image (mobile) | Header logo image on mobile when *Logo type* is **Image**. Falls back to the desktop logo (or your Shopify brand logo) when empty. | Image (optional) | Mobile |

<Tip>
  The header logo is clickable: clicking it closes the search overlay, the same as the close (✕) button.
</Tip>

## Advanced

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Use custom product card | Render a `<gpt-search-product-card>` custom element instead of the default card. Requires registering the custom element with JavaScript. | On / Off · default `Off` | Desktop & Mobile |
| Disable top layer | Enable if you position the modal with custom CSS and need the rest of the page to stay interactive. Watch for z-index issues. | On / Off · default `Off` | Desktop only |

### Depict Search Styling

To edit these settings: **Shopify admin → Online Store → Themes → Customize → App embeds**, then expand **Depict Search Styling**.

Global visual styling of the search modal. The baseline stylesheet has sensible defaults, so the modal still renders correctly if this embed is disabled. Every setting below defaults to the look the modal had before the setting existed, so a store that never touches them sees no change.

## Shape & type

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Border radius | Corner roundness used across the modal: the search field, the filter / sort / grid-layout / "view all" buttons and their dropdowns, the product cards, and the in-card badges (kept slightly rounder than the card). Set to `0` for fully square corners everywhere. | `0`–`30` px (step 1) · default `10px` | Desktop & Mobile |
| Base font size | Base font size for the whole modal. Every other text (headings, labels, results) scales relative to this. An absolute unit (px) stays fixed; a relative unit (em / %) scales with your store's base font size. Leave empty to inherit your store's font size. | CSS font size (optional) | Desktop & Mobile |
| Match store typography | By default the search field, the suggestions and the chips never drop below 16px, whatever the base font size. Turn this on to let them follow your store's font size exactly on desktop. On mobile they keep the 16px minimum, which stops phones from zooming in when the field is focused. Small labels keep their accessibility minimums either way. | On / Off · default `Off` | Desktop (mobile keeps 16px) |
| Section heading style | How the headings above the suggested searches and the top picks are set: small uppercase labels with letter-spacing, or sentence case in the body size. | Small caps, Sentence case · default `Small caps` | Desktop & Mobile |

## Search field

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Search field style | The shape of the search field. **Boxed** draws a frame around it, filled, with the global border radius. **Underline** is a single rule under the text, no fill, no radius; the rule darkens while typing. **Bare** shows only the icon and the text; the icon darkens while typing. | Boxed, Underline, Bare · default `Boxed` | Desktop & Mobile |
| Surface style | **Elevated** keeps the soft shadows and glass effects on the field, the filter and sort buttons and the dropdowns. **Flat** removes them and leaves hairline borders. | Elevated, Flat · default `Elevated` | Desktop & Mobile |
| Loading indicator | What moves while results load. **Gradient around the field** runs a light sweep along the field's frame and blurs the previous results. **Thin line under the field** draws a 2px line after a short delay and dims the previous results. **Quiet** only dims the previous results. Underline and bare fields have no frame, so they use the thin line in place of the gradient. | Gradient around the field, Thin line under the field, Quiet · default `Gradient around the field` | Desktop & Mobile |

## Product card

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Text case | Text casing for product card text. | None, Capitalize Each Word, UPPERCASE, lowercase, full-width, Full-size Kana · default `None` | Desktop & Mobile |
| Font family | Font for product card text. Enter a CSS font-family value, e.g. `"Poppins", sans-serif`. Leave empty to inherit the modal font. | CSS font-family (optional) | Desktop & Mobile |
| Font size | Font size for product card text. Leave empty to use the Base font size, falling through to your store's font size when that is also empty. | CSS font size (optional) | Desktop & Mobile |
| Sale price color | Color of the sale price when a product is on sale. Leave empty for the default. | Color (optional) | Desktop & Mobile |
| Original price color | Color of the original (crossed-out) price when a product is on sale. Leave empty for the default. | Color (optional) | Desktop & Mobile |

## Modal styling

| Setting | Description | Values / Default | Applies to |
| - | - | - | - |
| Enable dark theme | Applies dark styling to the entire modal. | On / Off · default `Off` | Desktop & Mobile |
| Background colour | Background of the search modal, its dropdowns, sticky bars and filter panel. Used in light and dark theme alike, so pick a dark colour if dark theme is on. Leave empty for the default. | Color (optional) | Desktop & Mobile |
| Search field colour | Background of the search field, also while typing. Used in light and dark theme alike. Leave empty for the default. | Color (optional) | Desktop & Mobile |
| Custom CSS | Free-form CSS injected globally into the modal, for anything the settings above do not cover. | CSS (optional) | Desktop & Mobile |

<Tip>
  **A storefront with small type and no shadows**, such as a fashion theme set in 14px Helvetica: turn on *Match store typography*, set *Surface style* to Flat or *Search field style* to Underline, set *Loading indicator* to Thin line, and *Section heading style* to Sentence case. The heading text itself ("Our Top Picks") is set in the layout embed.
</Tip>

## Reports

Search metrics live on the [Analytics](/shopify-lite/product-analytics) page
under its Search section, and in the [weekly report](/shopify-lite/weekly-reports).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.