Skip to content

Custom theme integration checklist

Guide type: Task guide
Difficulty: Advanced
Applies to: Custom Shopify themes, headless stores

Use this checklist when integrating SmartSize with a custom or heavily modified Shopify theme. Complete each step in order to verify that SmartSize loads, displays, and functions correctly on your storefront.

Before you start

You need:

  • a live Shopify store with a custom or modified theme
  • access to the Shopify theme editor
  • a published product to test with
  • SmartSize installed and at least one size chart or fit quiz created

Architecture notes

SmartSize is built with Preact, styled-components, and Nanostores, bundled as an IIFE widget that renders inside a Shadow DOM. It communicates with the Shopify storefront through app embeds and app blocks.

  • Breakpoints: Mobile = max-width: 768px
  • Coordinate system: The mannequin visualization uses a 600×615 coordinate space with CSS transform: scale()
  • Font loading: The widget loads its own fonts to avoid theme dependencies

Step 1: Verify theme supports app embeds

Most standard Shopify themes (Dawn, Refresh, Craft, etc.) support app embeds. Custom and headless themes may not.

  • Open the Shopify theme editor for your live theme.
  • Go to App embeds in the left sidebar.
  • Confirm that the SmartSize app embed appears in the list.
  • If SmartSize does not appear, your theme may bypass standard Shopify theme architecture. You may need a custom integration using the JavaScript API or manually placed script tags.

If app embeds are not supported: See SmartSize app embeds for custom themes and JavaScript API overview for alternative integration paths.

Step 2: Add required theme hooks

SmartSize needs specific DOM hooks to anchor the popup and inject scripts correctly.

  • Confirm the product page template includes a <head> section where app embed scripts can load.
  • Confirm the product form or product information section has a stable container element for button placement.
  • If using automatic placement, verify the product form has a standard Shopify structure (form with action="/cart/add").
  • If automatic placement fails, switch to floating button or app block placement in SmartSize Global settings.

Test: Save the theme and load a product page. Check the browser DevTools Elements panel for a <smartrecom-host> or Shadow DOM container.

Step 3: Turn on app embeds and save

  • In the Shopify theme editor, find SmartSize in App embeds.
  • Turn on the Size chart app embed (if using size charts).
  • Turn on the Fit quiz app embed (if using fit quizzes).
  • Click Save.
  • Wait for Shopify to confirm Changes saved.

Step 4: Verify SmartSize loads on the storefront

  • Open a live product page (not the theme editor preview).
  • Open browser DevTools → Console.
  • Type window.SmartRecom and press Enter.
  • Confirm the output is an object (not undefined).
  • Type window.SmartRecom.isReady() and confirm it returns true.
  • If isReady() returns false after 5 seconds, check the Network tab for blocked scripts or CORS errors.

Step 5: Test the SmartSize button

  • Look for the Size Chart or Find my size button on the product page.
  • If the button is missing:
  • Check that a size chart or fit quiz is Active in SmartSize
  • Check that the product matches the product display rules
  • Try floating button placement in Global settings
  • See SmartSize button is missing from my product page
  • Click the button and confirm the popup opens.
  • If the popup does not open, check the Console for JavaScript errors.

Step 6: Test the quiz flow (if using fit quizzes)

  • Open the fit quiz popup.
  • Complete each step (measurements, multiple choice, bra size if applicable).
  • Confirm the size recommendation appears on the winner screen.
  • Verify the recommended size is displayed prominently.
  • Check that the size chart opens correctly from the recommendation screen.

Step 7: Test the size chart (if using size charts)

  • Open the size chart popup.
  • Confirm the table displays correctly with no cut-off columns.
  • Verify measurements are readable.
  • Check that images load and are not broken.

Step 8: Test on mobile

  • Open a product page on a mobile device or use browser DevTools device emulation.
  • Tap the Size Chart or Find my size button.
  • Confirm the popup fits within the screen.
  • Verify text is readable without zooming.
  • Check that the close button is easy to tap (minimum 44×44px).
  • Scroll through quiz steps and confirm no content is clipped.
  • Complete the quiz and confirm the recommendation screen displays correctly.

Common mobile issues:

  • Fit labels clipped on the right edge → increase mannequin container padding
  • Slider initial values too low → verify default values in theme settings
  • Step dots too small → SmartSize uses a progress bar on mobile by default

Step 9: Verify CSS resilience

  • Install a browser extension that modifies page styles (dark mode, font changer).
  • Reload the product page and open the SmartSize popup.
  • Confirm the popup appearance is unchanged by the extension.
  • Check that fonts, colors, and spacing inside the popup match SmartSize's intended design.

If styles are affected: See Styling resilience and conflict prevention.

Step 10: Validate accessibility

  • Navigate the quiz using only the Tab key.
  • Confirm all interactive elements (buttons, inputs, options) are focusable.
  • Verify focus indicators are visible.
  • Confirm the Escape key closes the modal.
  • Check color contrast with a browser extension or DevTools.
  • Verify screen reader announcements for the recommendation result.

Step 11: Test after theme updates

After any theme code update, repeat steps 4–8:

  • SmartSize loads (window.SmartRecom.isReady()).
  • Button appears.
  • Popup opens.
  • Quiz completes.
  • Mobile experience is correct.

If SmartSize stops working after a theme update: See SmartSize stopped working after a theme change.

Check the result

After completing this checklist, you should have:

  • SmartSize app embeds active on your live theme
  • The SmartSize button visible on product pages
  • The popup opening and closing correctly
  • The quiz or size chart rendering without layout issues
  • A clean mobile experience
  • No visual interference from browser extensions or theme CSS
  • Accessible keyboard navigation

Next steps