SmartSize app embeds for custom themes¶
Guide type: Reference Difficulty: Advanced Applies to: Developers & custom themes
How SmartSize app embeds and app blocks work with custom Shopify themes, and what developers need to know for advanced integrations.
Can I use SmartSize on a custom Shopify theme?¶
Yes. SmartSize supports both standard Shopify themes and custom or heavily modified themes through app embeds, app blocks, and a JavaScript API for headless integrations. Most standard themes work out of the box with automatic button placement. Custom themes may need manual placement or app blocks for precise control.
App embeds vs app blocks¶
SmartSize uses two Shopify extension types to appear on the storefront:
| Type | What it does | Merchant control |
|---|---|---|
| App embed | Loads the SmartSize JavaScript and CSS globally on the theme. Creates the popup container and button injection system. | On/off toggle, button text, colors, placement method |
| App block | Places a SmartSize button at a specific location in a theme section using the Shopify theme editor. | Position inside the section template |
Most merchants use app embeds because they require less manual placement. App blocks are useful when a theme structure blocks automatic placement and the merchant wants precise control over button location.
Placement methods¶
SmartSize offers several ways to place the storefront button. Each method has different theme compatibility.
Automatic placement¶
SmartSize tries to find a stable CSS selector inside the product form and injects the button automatically.
| Behavior | Details |
|---|---|
| Target | The product variant form or a known product-information container |
| Selector | Theme-dependent; SmartSize maintains a list of common selectors |
| Fallback | If no stable selector is found, SmartSize shows a warning and suggests alternatives |
Automatic placement works with most standard Shopify themes. Custom themes with heavily modified product templates may need one of the other methods.
Floating button¶
The button appears as a floating tab or widget at a fixed screen position, independent of the product form structure.
| Behavior | Details |
|---|---|
| Position | Configurable: bottom-left, bottom-right, side-left, side-right |
| Z-index | Set high to float above page content |
| Mobile | Can switch to full-width or remain floating |
This is the most reliable placement method for custom themes because it does not depend on the product form structure.
App block placement¶
The merchant drags a SmartSize app block into a specific section of the product template in the Shopify theme editor.
| Behavior | Details |
|---|---|
| Location | Exactly where the merchant places it in the theme editor |
| Template | Product template only; requires the section to support app blocks |
| Product context | The app block reads the product from the surrounding template context |
Custom selector placement¶
SmartSize injects the button into a CSS selector specified by the merchant or developer.
| Behavior | Details |
|---|---|
| Selector | Any valid CSS selector string |
| Insertion | Before, after, or inside the matched element |
| Validation | SmartSize checks whether the selector matches on the current page |
For detailed custom selector setup, see Choose where the SmartSize button appears.
Theme editor integration¶
When a merchant turns on an app embed in the Shopify theme editor, SmartSize registers itself as an app embed block with these settings:
| Setting | Type | Description |
|---|---|---|
| Button text | Text | Label shown on the storefront button |
| Button style | Select | Visual style preset |
| Icon | Toggle | Whether to show an icon next to the label |
| Text color | Color | Button text color |
| Background color | Color | Button background color |
| Corner radius | Range | Button border rounding |
These settings are saved per theme. If the merchant changes themes, the settings must be reconfigured in the new theme.
Custom theme checklist¶
For a step-by-step integration checklist, see Custom theme checklist.
Known limitations¶
- App embed settings are tied to a single theme. Draft themes do not affect the live storefront.
- Custom themes that render the product form asynchronously may cause automatic placement to fail until the DOM is fully ready.
- SmartSize cannot inject buttons into Shadow DOM containers.
- Some third-party apps that modify the product page may conflict with automatic selector detection.