OYLABS
OYLABS
OY LabsSwatchBoostDocumentation
Getting Started
SwatchBoost

SwatchBoost Documentation

SwatchBoost is a Shopify Theme App Extension that intercepts the Add to Cart action on product pages, shows a multi-colour picker popup, and automatically applies tiered bulk discounts — all with zero code and full RTL support.

Overview

  • Works as a Shopify Theme App Extension — no theme code injection required
  • Variant data is server-rendered via Liquid — zero page speed impact
  • All intercepts (fetch, XHR, form submit) are set up client-side before the page is interactive
  • Config (branding, tiers, copy) is fetched from the app server at runtime and cached for 60 seconds
  • Fully compatible with Online Store 2.0 themes

Installation

Installing SwatchBoost takes under 5 minutes and requires no developer access.

1

Install from the Shopify App Store

Visit the SwatchBoost listing and click Add app. Approve the permissions.

2

Enable the App Embed

In your Shopify admin go to Online Store → Themes → Customize → App embeds. Find SwatchBoost Popup and toggle it on. Click Save.

3

Activate your first product

In the SwatchBoost app, go to Products and click Activate next to any product that has a Colour option.

4

Test on your storefront

Open a product page and click Add to Cart. The SwatchBoost popup should appear.

Dev store? All Growth plan features are unlocked automatically for partner development stores — no billing required.

Quick Start Checklist

  • App installed and permissions approved
  • App Embed toggled on in theme editor and saved
  • At least one product activated in the Products tab
  • Product has a Color or Colour option with 2+ variants
  • Test on storefront: popup appears when clicking Add to Cart
How It Works

The Popup Flow

SwatchBoost intercepts the Add to Cart action using three strategies in order of reliability:

  1. 1.fetch override — replaces window.fetch globally. When the theme posts to /cart/add.js, the override opens the popup and returns a fake 200 response so the theme UI does not break.
  2. 2.Form submit listener — captures submit events on forms with action="/cart/add" or data-type="add-to-cart-form" at the document level (capture phase).
  3. 3.Click listener — document-level capture listener that walks up the DOM from the clicked element looking for an Add to Cart button by name, class, or form context.

Colour Detection

SwatchBoost detects your colour option automatically via Liquid on the server, so there is no client-side guessing. The liquid template reads product.options and finds the first option whose name matches:

Liquid
color, colour, اللون, couleur, farbe

If no match is found, the first option is used. The variant data (IDs, prices, availability) is injected directly into the page as window.__SB_VARIANTS__ — a JSON array available immediately when the script runs, before any fetch calls.

Live Cart Sync

When a customer taps a colour swatch in the popup:

  • Selecting a colour makes a POST /cart/add.js request immediately. The swatch shows a spinner while the request is in flight.
  • Deselecting a colour calls POST /cart/change.js with quantity 0, removing just that variant from the cart.
  • The cart is updated in real time — no page reload needed.
  • The View Cart button updates to show the live colour count.
The pre-selected colour (the one the customer originally chose on the product page) is automatically added to cart when the popup opens.
Customizer

Brand Themes

SwatchBoost ships with three ready-made brand presets. Select one in the Customizer tab of the app.

Preview

Premium Boutique

White, gold, serif — luxury fashion and accessories

Preview

Bold & Energetic

Dark background, green — streetwear, sports, tech

Preview

Warm & Regional

Cream, terracotta — Middle East, regional boutiques, RTL stores

Custom Copy

On Starter and Growth plans you can customise every text string shown in the popup:

  • Headline — main title inside the popup (e.g. "Style it in more than one.")
  • Subheadline — short supporting line (e.g. "Select colours — each adds to cart instantly.")
  • CTA text — the checkout button label
  • Max tier text — shown when the highest discount tier is reached

Discount Tiers

Default tiers are set globally in the Customizer. On Starter and Growth plans you can customise the minimum quantity and discount percentage for each tier.

Default tiers
2 colours → 5% off
3 colours → 10% off
4+ colours → 15% off
Tiers are informational in the popup. For the discount to actually apply at checkout you must set up Automatic Discounts in Shopify Admin — see the Discounts section below.

Accent Colour

You can override the accent colour (used for progress bar, pill, swatch selection ring, and CTA) with any hex value. This is available on Starter and Growth plans.

RTL & Languages

RTL & Arabic Support

SwatchBoost is the only colour-swatch upsell app verified to work natively in RTL languages. No other top-tier Shopify swatch app supports this.

How RTL Works

SwatchBoost detects the store language direction from the dir attribute on the <html> element. When dir="rtl" is set:

  • The popup panel mirrors horizontally — close button moves to the left, content reads right-to-left
  • The progress bar fills from right to left
  • Swatch check badges reposition to the correct corner
  • The Warm & Regional brand preset uses Cairo font which renders Arabic text correctly

Arabic Setup

If your Shopify store serves Arabic (or any RTL language), follow these steps:

1.In Shopify Admin → Online Store → Themes → Languages, add Arabic.
2.Ensure your theme sets dir="rtl" on the <html> element when Arabic is active. Most OS 2.0 themes do this automatically.
3.In SwatchBoost Customizer, select the Warm & Regional theme preset for optimal Arabic typography.
4.If your option names are in Arabic, add them to the colour detection list via the Products tab — contact support for custom option name mapping.

Supported Languages

The popup UI works in any language your store serves. The following RTL languages are explicitly tested:

Arabic (العربية)Hebrew (עברית)Persian (فارسی)Urdu (اردو)
Products

Activating Products

SwatchBoost only activates on products you explicitly enable. This prevents the popup from appearing on products with non-colour variants (size, material, etc.).

  1. Go to SwatchBoost app → Products tab
  2. Your store's products are listed. Products with a Color / Colour option are highlighted
  3. Click Activate on any product to enable the popup
  4. Click Deactivate to disable it for that product

Colour Option Names

SwatchBoost automatically detects the colour option if it is named one of the following (case-insensitive):

color, colour, اللون, couleur, farbe

If your store uses a different name (e.g. "Shade", "Hue", "Finish"), contact support and we will add it to your account's detection list.

Products with 1 Colour Variant

If a product has only 1 colour variant, SwatchBoost will not activate on that product page — the popup requires at least 2 variants to show. The Add to Cart action passes through normally.
Discounts

Automatic Discount Setup

SwatchBoost shows the savings to customers in the popup, but the actual discount must be created in Shopify Admin as an Automatic Discount. This is a one-time setup.

1

Go to Shopify Admin → Discounts → Create discount → Automatic discount

Select "Amount off products" or "Buy X get Y" depending on your store setup.

2

Configure a tier — example: 2 colours = 5% off

Set "Minimum quantity of items" to 2, discount value to 5%, and target to "Specific products" (select the same products you activated in SwatchBoost).

3

Repeat for each tier

Create three automatic discounts — one for 2+, one for 3+, one for 4+ items. Shopify will apply the best applicable discount automatically.

4

Test in your storefront

Add 2+ colours via SwatchBoost, go to checkout, and verify the discount appears in the order summary.

Shopify Plus merchants can use Shopify Scripts or Shopify Functions for more advanced discount stacking. Contact OY Labs for a custom implementation.
Plans & Billing

Plan Comparison

FeatureFreeStarterGrowth
Price$0$9.99/mo$24.99/mo
Free trial—7 days7 days
Products1Up to 10Unlimited
Default discount tiers✓✓✓
Custom discount tiers—✓✓
RTL support✓✓✓
Custom accent colour—✓✓
Custom popup copy—✓✓
Brand presets—2All 3
Full custom branding——✓
Analytics dashboard——✓
Priority support——✓

Free Trial

All paid plans (Starter and Growth) include a 7-day free trial on first install. You will not be charged until the trial ends. Cancel at any time from Shopify Admin → Apps → SwatchBoost → Cancel subscription.

Developer & Partner Stores

If you are installing SwatchBoost on a Shopify Partner development store, all Growth plan features are unlocked automatically at no charge. This allows full testing before presenting to clients.

Troubleshooting

Troubleshooting

Popup not showing when clicking Add to Cart

  • Confirm the App Embed is toggled on in your theme editor and the theme has been saved
  • Confirm the product is activated in the Products tab
  • Confirm the product has a Color or Colour option with at least 2 available variants
  • Hard-refresh the product page (Cmd+Shift+R / Ctrl+Shift+R) to clear CDN cache
  • Check the browser console for any JavaScript errors prefixed with [SwatchBoost]

Discount not applied at checkout

  • Verify you have created Automatic Discounts in Shopify Admin → Discounts (see Discounts section)
  • Ensure the automatic discount targets the same products activated in SwatchBoost
  • Check the discount is active and not expired
  • Test in a fresh browser session (not logged in as admin) — some admin-only discounts do not apply in preview mode

RTL layout issues

  • Ensure your theme sets dir="rtl" on the <html> element when the RTL language is active
  • Use the Warm & Regional brand preset for best Arabic typography
  • If colour option names are in Arabic, contact support to add custom option name detection
Still stuck? Email hello@oylabs.co with your shop domain and a description of the issue. Growth plan customers receive priority response within 24 hours.
SwatchBoost overviewInstall App