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.

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 page
Results per row
CSS Wrapper Class
Pagination Style

When Local Inventory is configured, the filter uses the active location's editable storefront display name. New display names default to the Shopify Admin location name, while locations without a saved name keep the generic Local Store heading. 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, clears local fulfillment selections and the active place, and refetches the collection. 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 Autocomplete 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 six 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.

Layout & Behavior

Setting	Behavior
Position	Displays the dialog in the center of the screen or full width at the top.
Trigger Selectors	Sets which storefront search inputs or controls open Dynamic Autocomplete. Enter one valid CSS selector per line.
Open on Focus	Opens the dialog when shoppers focus or tap a matching trigger.
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.

Dynamic Autocomplete attaches to input[name="q"] search fields by default. Merchants can add up to ten selectors when a theme uses different search inputs. Add data-rcc-autocomplete="off" to a specific search input when it should keep the theme's native autocomplete behavior.

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.

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 number of product cards.
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 best sellers or products from a selected collection.
Product Source	Selects Best Sellers or Collection.
Collection	Searches the store's Shopify collections when Collection is selected.
Default Product Limit	Limits the number of default product cards.

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