# 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](https://www.nimstrata.com/contact) 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. !!!info 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. ==- Search Results The **Search Results** App Block installs on Shopify's default search template. ==- Collection Pages 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. ==- Recommendations AI 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 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. !!!info 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 {.compact} | 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 {.compact} | 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 {.compact} | 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 {.compact} | 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 {.compact} | 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 {.compact} | 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](/google-cloud-vertex-ai-search-for-commerce/recommendations-ai/) for model details. #### Recent Searches {.compact} | 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 {.compact} | 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](/shopify/translations/) page. ==- Document Search 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](/shopify/advanced-settings/google-cloud/#document-search). ===