Shopify App Blocks

Theme Compatibility

Retail Cloud Connect works best with Shopify Online Store 2.0 themes that support App Blocks.

If the current theme does not support App Blocks, contact Nimstrata for assistance with deploying Retail Cloud Connect on that theme.

Search and collection App Blocks use the connected app project and the default_search serving configuration. Recommendations AI blocks have their own Serving Configuration ID setting because each recommendation block can use a different model or placement.

Published Theme Status

The Retail Cloud Connect Shopify App dashboard checks installation status on the selected theme. If merchants configure an unpublished theme first, the dashboard may still show a component as incomplete until the selected or published theme matches those changes.

Choose Storefront Settings for a Theme Surface

The native Settings profile picker is available on exactly four Retail Cloud Connect theme surfaces:

Search Results
Product Grid
Dynamic Autocomplete
Recommendations AI

Leave the picker blank to use Production. A missing or deleted profile also falls back to Production. Dynamic Autocomplete exposes the picker in its App Embed settings; the other three expose it in their App Block settings.

See Storefront Settings Profiles to create profiles, compare them with Production, retry publishing, and promote a profile.

Search Results and Collection Pages

Retail Cloud Connect ships dedicated App Blocks for the Shopify Search and Collection templates.

Both blocks support:

Style
Show Search Bar
Content Position
Results per row
CSS Wrapper Class
Pagination Style

Search and collection product grids use a fixed repeating 36, 36, 48 result schedule. This is not a merchant-configurable App Block setting.

When Local Inventory is configured, the filter uses the active location's editable storefront display name. Newly selected locations start without a saved display name and keep the generic Local Store heading until one is set. Named locations show Local Store as a smaller, regular-weight line above the store name. Change Store appears in the same position and style as other filter Clear actions. It keeps the active place and local fulfillment selections until a new place is set, and closes the surrounding native filter dialog. It can be hidden with the localInventory.showChangeStoreButton search setting.

The Search Results App Block installs on Shopify's default search template.

The Product Grid App Block installs on Shopify's default collection template and additionally supports Show Collection Description.

The dashboard and Theme Installation page show a critical Duplicate Sections Detected alert above the Installation Summary table when the theme's native search results or product grid is still enabled alongside a Retail Cloud Connect block, or when more than one enabled Retail Cloud Connect block of the same type is present. Open Manage, hide the native results section with Shopify's eye icon, and keep one Retail Cloud Connect block enabled.

The Recommendations AI App Block can be installed on more than just product pages. The dashboard installation status focuses on the product-page recommendations block, but the current extension supports:

Product pages
Collection pages
Cart pages
Home page
Blog posts
Articles
Standard pages

The default serving configuration is recently_viewed_default.

Common settings include:

Serving Configuration ID
Header Text
Sub-Header Text
Show Sub-Header Text
Number of Recommendations
Results per row
Style

Autocomplete is enabled separately from the main search results App Block and is designed to enhance the theme's primary search box. Two app embeds are available:

Keyword Autocomplete provides the legacy text-suggestion experience. Its Enable Shopify Fallback setting can use existing Shopify search traffic to help train the model.
Dynamic Autocomplete is the full experience configured from the app's Autocomplete settings page and enabled with its App Embed in the Theme Editor. It supports text and brand suggestions, independent collection and page results, exact SKU navigation, and up to eight product previews.

The legacy text-only autocomplete model can take a few days to start learning from existing search traffic and typically one to two weeks to mature on active stores.

Enabling Dynamic Autocomplete

In the Shopify admin, go to Online Store > Themes and click Customize on your active theme.
Open App Embeds (the puzzle-piece icon), toggle on Dynamic Autocomplete, and click Save.
In the Retail Cloud Connect app, open the Autocomplete settings page to choose which surfaces appear: keywords, products, brands, collections, pages, and predefined suggestions.

That is the whole installation for most stores. There is no theme code to edit: once the embed is on, Dynamic Autocomplete finds your theme's search box and takes over from there.

If you were previously using Keyword Autocomplete, toggle its embed off when you enable Dynamic Autocomplete so the two experiences do not compete for the same search input.

How It Takes Over the Search Bar

Dynamic Autocomplete attaches to the search inputs your theme already has:

It finds the standard search box automatically. Shopify themes submit search with an input named q, so Dynamic Autocomplete attaches to input[name="q"] by default. When a shopper taps or focuses that input, the Dynamic Autocomplete dialog opens with its own search field, and the theme's built-in suggestions never appear.
Search boxes that appear later are picked up too. Many themes only render their search field inside a drawer or popup after the shopper taps a search icon. Dynamic Autocomplete watches the page for search inputs that are added or replaced after load and attaches to them the moment they appear.
Custom themes can add their own selectors. If your theme uses a search input without name="q", add up to ten CSS selectors (one per line) in the Trigger Selectors setting under Layout & Behavior. Any element matching a selector becomes a trigger: inputs open the dialog on focus when Open on Focus is enabled (the default), and non-input elements like a search icon open it on click.
Any element can become a search button. Add aria-controls="rcc-dynamic-autocomplete" and aria-haspopup="dialog" to a button, link, or icon in your theme. Shopify theme markup can instead use on:click="#rcc-dynamic/showDialog". Either option opens Dynamic Autocomplete without selector configuration, prevents the element's default action, and restores focus to it when the dialog closes.
Individual inputs can opt out. Add data-rcc-autocomplete="off" to a specific search input to keep the theme's native behavior there, for example a blog-only sidebar search.

Shoppers can also press / anywhere on the page (outside another text field) to open Dynamic Autocomplete focused and ready for typing.

If the dialog is not opening

Symptom	Likely cause and fix
The theme's own suggestions still appear	The Dynamic Autocomplete App Embed is off, or the input has `data-rcc-autocomplete="off"`.
Nothing happens on the header search	The input is not named `q`. Inspect it and add its CSS selector to Trigger Selectors.
Works on desktop, not in the mobile search drawer	The drawer input uses a different selector than the desktop one. Add both selectors, one per line.
A specific search box should stay native	That is the supported opt-out: add `data-rcc-autocomplete="off"` to that input.

Layout & Behavior

Setting	Behavior
Position	Displays the dialog in the center of the screen or full width at the top.
Product Display	Chooses Responsive (default), Grid, or Slider for searched, recommended, and default product sections in either dialog position.
Trigger Selectors	Sets which storefront search inputs or controls open Dynamic Autocomplete. The default is `input[name="q"]`; enter one valid CSS selector per line to replace it.
Open on Focus	Opens the dialog when shoppers focus or tap a matching search input. Enabled by default.
Minimum Query Length	Sets how many characters a shopper must enter before AI Predictions start returning results.
Keyword Debounce (ms)	Delays keyword and lightweight Shopify suggestion requests while shoppers type.
Product Debounce (ms)	Delays billable AI Commerce Search product requests while shoppers type.

The debounce controls are collapsed under Advanced Settings. Their saved values continue to apply while the controls are hidden.

See How It Takes Over the Search Bar above for how Trigger Selectors interact with the default input[name="q"] attachment, the per-input opt-out, and custom open triggers.

AI Predictions

Keywords

Setting	Behavior
Keyword Suggestions	Shows AI Commerce Search predictions for common text, brand, and collection searches.
Keyword Suggestion Limit	Limits the number of keyword predictions.
Shopify Fallback	Shows Shopify query suggestions when AI Commerce Search returns no text suggestions.
Fallback Query Limit	Limits the number of Shopify fallback suggestions.

Both autocomplete experiences can include queries from enabled Retail Cloud Connect redirect rules and active Google Cloud redirect controls. They look like ordinary keyword suggestions, appear before other predictions, are deduplicated, and count toward the existing suggestion limit. Automatically generated brand (vendor) and sale redirects are not included. No more than two redirect terms are added. Keyword Autocomplete shows up to eight suggestions overall. Dynamic Autocomplete uses its configured suggestion limit and shows no more than six overall.

Redirect suggestions match exact text first, then prefixes. Only when neither matches can they correct one missing, extra, or substituted character, or one pair of adjacent characters in the wrong order after at least three characters. Selecting the suggested full phrase uses its redirect, but pressing Enter on a misspelling still runs a normal search. See Search Redirects for the full storefront behavior.

Products

Setting	Behavior
Product Suggestions	Shows initial product results from AI Commerce Search while shoppers type. Each request is billable.
Product Suggestion Limit	Limits the product grid to eight cards. Mobile renders them in two columns and up to four rows.
Exact SKU Result	Shows a direct product result when Shopify finds an exact SKU match. The exact match replaces the product grid, and Enter opens the matched variant.
SKU Minimum Length	Sets the minimum number of characters checked for an exact SKU.

Additional Suggestions

Setting	Behavior
Brand Suggestions	Shows matching Shopify product vendors alongside keyword suggestions.
Group Suggestions by Type	Separates query suggestions from direct collection, page, brand, and SKU destinations. Turn it off to use one combined list.
Collection Suggestions	Shows matching Shopify collections as direct navigation results.
Page Suggestions	Shows matching Shopify pages as direct navigation results.
Pages and Collections Limit	Limits the combined collection and page results.

Each AI Predictions source can be enabled independently. Product searches run separately from faster keyword, brand, collection, page, and SKU lookups so lightweight suggestions can appear first.

Predefined Suggestions

Predefined Suggestions appear before a shopper begins typing.

Default Products

Setting	Behavior
Default Products	Shows bestsellers or products from a selected collection.
Product Source	Selects Bestsellers or Collection.
Collection	Searches the store's Shopify collections when Collection is selected.
Default Product Limit	Limits the number of default product cards.

The single-select collection picker loads an initial list quickly, then searches the complete Shopify collection catalog as a merchant types. Products retain Shopify's collection order. On the storefront, the collection heading uses the collection title translated for the shopper's active language when one is available.

Personalized Products

Setting	Behavior
Recommendations AI	Shows personalized products from a compatible Recommendations AI serving configuration.
Serving Configuration	Selects an available configuration from the connected Google Cloud project.
Personalized Product Limit	Limits the number of personalized product cards.

The serving-configuration dropdown excludes AI Commerce Search configurations and recommendation models that need a context product. It includes configurations backed by Recommended for You, Buy it Again, On sale, and Recently Viewed models. Page-level Optimization is not supported because its first response contains serving configuration IDs rather than products. See Recommendations AI for model details.

Recent Searches

Setting	Behavior
Recent Searches	Shows shoppers their recent successful searches for the current store and locale.
Recent Searches Limit	Limits the number of recent searches.

Shoppers can clear their recent searches directly from the Dynamic Autocomplete dialog.

Sample Queries

Setting	Behavior
Sample Queries	Shows curated suggestions before shoppers type.
Sample Query 1–5	Sets up to five merchant-defined examples.

Sample queries can be translated from the app's Translations page.

The Document Search App Block can be added to Shopify page templates when document search is enabled for the store.

The block requires an Engine ID from the connected document search setup and renders ten document results per request. Document Search uses the storefront language and country from Shopify localization.

For document search prompts and Google Cloud settings, see Google Cloud.