Search widgets

Search shows on your storefront through three widgets: the search modal, the search results page, and autocomplete. This page explains each one and its settings.

The three search widgets

You add app blocks in the Shopify theme editor. See Add widgets to your theme.

The search modal

The modal is a search overlay. It opens when the shopper clicks your theme's own search icon, because the app embed takes it over by default (Open PersonalizerAI search from your theme's search in the embed settings), and from the Cmd+K / Ctrl+K shortcut while that setting is on. The takeover recognises Horizon, Dawn and themes built like them, and any header link to your search page. On another theme your search icon may still open the theme's own search: click it on your store to check. If it does, enter your search button's CSS selector in Search button selector (advanced) in the same embed settings, or add the Search (header) block. It also opens from the Search (header) or Search (section) block, if you added one, and from any button or link that you, your developer or a page builder (PageFly, GemPages) marked with data-pai-search-trigger — no script needed, so it keeps working in a builder that removes scripts. Add data-pai-search-query="snowboard" to open it with that text already typed. Inside the modal, the shopper gets:

• A search box with suggestions and the shopper's last 5 searches. Recent searches are saved in the shopper's own browser (local storage) for 30 days and shown when the box is empty. They are never sent to our servers. The shopper can remove one (its ×, or the Delete key) or all of them (Clear history). You can turn them off or change how many show in Search experience.
• Your store's popular searches, also shown when the box is empty. A shopper clicks one to search for it. See Popular searches.
• A results grid with filters and a sort menu. Choose how the modal opens, which sections the dropdown shows, the sorts, where filters sit, and how more results load in Search → Search experience, and see your changes on your own store before you save them with Preview on my store. See Style your widgets.
• A Popular right now block when a search finds nothing, if the app can load the product prices in time. Turn it off with Show popular products in Search → Search experience → No results. See How search works.

The search modal with results, filters, and a sort menu.

"Your theme's search icon can't open PersonalizerAI search"

You see this warning in the Shopify admin (Widgets → Cart & search, on the Search results page card) and in Search → Search experience when your store told the app that it could not find your theme's search button. Shoppers who click your search icon then get your theme's own search, not PersonalizerAI search. The warning names the theme, says whether it happens only on phones or only on desktop (themes often show a different search button on each), and when it was last seen.

Fix it either way:

1. Add the Search (header) block to your header. The warning's Add Search (header) block button opens the theme editor at your header with the block ready to add. Then save. You can hide your theme's own search icon in the header settings, so shoppers see one icon.
2. Or tell the app which button is your search button. The warning's Set the search button selector button opens App embeds → PersonalizerAI. Enter the button's CSS selector in Search button selector (advanced) and save. If the warning says your selector matches nothing, the selector you entered does not find the button on those pages: check it on a phone-sized screen too.

The warning goes away by itself 3 days after the last visit that ran into it, so after you fix your theme it can stay for up to 3 days. It does not show while the app embed is off (a different message covers that), when you turned off Open PersonalizerAI search from your theme's search, or for a theme that is not published. The app checks only pages that have a header (not checkout, account or password pages) and never in the theme editor or a preview. What it sends is about your theme, never the shopper: see Privacy & consent.

Place the modal button

Two app blocks open the modal. Search (header) puts a search button in your theme header. Search (section) puts the same button inside a page section. Use the header block for most stores.

1. In your Shopify admin, open the theme editor.
2. Select the header area.
3. Click Add block.
4. Select Search (header). The theme editor shows the app name, PersonalizerAI, under the block name.
5. Click Save.

The header block has four settings: Icon color, Show button text, Button text, and Accessibility label.

The Search (header) block and its settings in the theme editor.

The search results page

Some shoppers use your theme's own search box and land on the search results page. The Search results app block replaces the results on that page with AI results. The shopper gets the same grid, filters, and sort menu as in the modal.

1. In your Shopify admin, open the theme editor.
2. Select the search results template.
3. Click Add section.
4. Open the Apps group.
5. Select Search results.
6. Hide the theme's own results section.
7. Click Save.

The block has four settings: Grid columns (2 to 6, or App default (Design) to use the desktop columns from the Design screen), Show filters sidebar, Results per page (8 to 40), and Default sort order (Store default uses the default sort from Search experience).

You can also start from the Shopify admin. Go to Widgets → Cart & search. On the Search results page card, click Place in theme editor. The theme editor opens on your search template with the block ready to add.

On this page and on collection pages, the Filters button and the sort menu stay at the top of the screen while the shopper scrolls, just under your theme's header, and a Back to top button appears after a few screens. The bar reads your theme's header height when the theme publishes it (Horizon does). If your header covers the bar, set the offset in custom CSS, for example :root { --pai-search-sticky-top: 72px; }.

The browser's Back button works the way shoppers expect. Each new search on this page is a step that Back returns to. A change of filter, sort or page is not a new step. When a shopper opens a product from the search modal, from this page or from a collection page and then goes back, the search is where they left it: the modal opens again on the same search, and the page shows all the results they had loaded, at the same scroll position. To do this, the search runs one more time. That search counts toward your monthly search total like any other search, except when the shopper was looking at a preview, on a collection page, or when the browser kept the page in memory.

The Search results block placed on the search template, with the theme's own grid hidden.

Autocomplete and the instant preview

While the shopper types, two things happen in the search box:

• Search suggestions appear under the box. This is Instant autocomplete. The suggestions are searches your shoppers really made, from your Popular searches list, that match what is typed so far. Your pinned terms come first and hidden terms never appear. A new store with no search history shows no suggestions until the nightly job has searches to list. The list under the box never shows products: the preview results below it already do.
• Your store's collections, pages and blog articles that match appear under their own headings (Collections, Pages, Articles), so a shopper can still reach a size guide, a shipping policy or a collection from search. These come from Shopify's own store search, which finds them by title and puts them in its own order. They are not part of Instant autocomplete, do not count toward your monthly search total, and do not appear in Search analytics. On a phone they sit in the same row as the suggestions, each with a link arrow. Turn each one off, or change how many show (up to 10), in Search → Search experience → Dropdown sections.
• Preview results appear in the grid after a short pause.

To see how often shoppers use the dropdown, go to Search and look at the Suggestion Clicks card above the tabs. It counts the searches that shoppers started by picking a suggestion, a popular search or a recent search in the dropdown. Each of these searches is also in Total Searches. The number updates once per night. It counts only shoppers who allowed analytics in your cookie banner, so the real number can be higher.

The preview uses keyword search only. The full AI search runs when the shopper presses Enter. Previews do not count toward your monthly search total, and they never trigger a redirect.

Because the preview uses keywords only, it can find nothing where the AI search finds products. So a preview that finds nothing does not say "No results". It shows a Search for "…" button instead. The button runs the full AI search, exactly like pressing Enter, and counts as one search. Nothing runs until the shopper presses it.

When a full search finds nothing, it can offer up to three other searches under Did you mean:. They come from your product titles (a misspelled word matched to the nearest word in a title) and from your store's popular searches, never including a term you hid under Popular searches. Pressing one runs that search and counts as one search. Nothing is replaced on its own: the shopper always sees that their own search found nothing.

1. Open the PersonalizerAI dashboard.
2. Go to Search.
3. Open the Basics tab.
4. Turn on Instant autocomplete.

Suggestions and preview results while the shopper types. The full AI search runs on Enter.

Popular searches

When the search box is empty, the modal shows up to 8 terms your shoppers search for most. The app builds the list every night from the last 30 days of searches. You can hide terms and pin your own.

A search counts only when all of these are true:

• The shopper submitted it — pressed Enter or picked a suggestion. Half-typed text never counts.
• The shopper allowed analytics in your cookie banner.
• Shoppers searched it in at least 3 different sessions in the last 30 days.
• It found at least one product.

The app also drops any term that could identify a person: a term with an @, a term shaped like a web address, or a term with 6 or more digits in a row, such as a phone or order number. It drops terms longer than 40 characters or 5 words too. The list holds counts only. It is never linked to a customer.

1. Open the PersonalizerAI dashboard.
2. Go to Search.
3. Open the Search experience tab.
4. In the Popular searches panel, click Hide on a term to remove it, or type a term under Pin a term and click Pin.
5. Click Save.

Shoppers see the change within 5 minutes. Pinned terms show first, in your order, and count toward the 8. A hidden term stays hidden, even if it becomes popular again.

To turn the section off, or show fewer than 8 terms, go to Search → Search experience → Dropdown sections. If no term qualifies and you pinned none, the section does not show.

The Popular searches panel: what shoppers see now, last night's candidates, and your pinned and hidden terms.

Change the text and the look

The search widgets follow your store's design settings. You can change any text shoppers see in search, in each of your store's languages, and the layout and the font of the modal. See Style your widgets. Search uses your Design colors, text sizes and corners, and the Search backdrop color dims the page behind the pop-up. For custom CSS (Growth and up), Style your widgets lists the search classes that stay the same between updates. The filters that appear come from your facet selection. See Ranking, curations & facets.

Your other apps in search

Search results are built from the same cards as your widgets, so your other apps can work with them:

• Review apps — star ratings show on search result cards, in list view and in Quick View. With Review app's own badge on, your review app's badge shows on the result cards. See Integrations.
• Wishlist and loyalty apps — the custom elements you set in Card defaults (for example a wishlist heart) show on result cards, list rows and in Quick View.
• Analytics — with the Google Analytics 4 or Meta Pixel integration on, searches and result clicks are forwarded, and your Shopify pixels can subscribe to personalizerai:search_submitted. See Integrations.
• Cart drawer apps — see Integrations for the event a drawer app needs after a quick add.
• Currency, label and other apps — every result carries its product id, handle and price for a developer to read, and search announces when results change. Your developer can find the details in the app's developer contract.