Product Color/Image Swatch Variant Plugin FAQs

Installation & Setup

Basic Plugin Implementation

Add this code to your site's header via Settings > Advanced > Code Injection:

<!-- Plugin Product Swatches -->
<link href="/s/plugin-swatches.css" rel="stylesheet">
<script src="/s/plugin-swatches.js"></script>
<script>
pluginProductSwatches({
    'variants': {
        'Red': ['red-shirt.jpg', 'red-shirt-back.jpg'],
        'Blue': ['blue-shirt.jpg', 'blue-shirt-back.jpg'],
        'Green': ['green-shirt.jpg', 'green-shirt-back.jpg']
    }
});
</script>
<!-- end Plugin Product Swatches -->

Why aren't my color swatches changing the product images?

Complete setup verification:

• Product variants configured - Set up in Commerce > Products

• Images properly uploaded - Each variant needs corresponding images

• Plugin files uploaded - Both CSS and JS to file manager

• Code injection added - Header section with correct configuration

• Naming conventions - Variant names must match plugin setup exactly

How do I set up the plugin for products with multiple color options?

Step-by-step process:

1. Configure product variants in Squarespace Commerce

2. Upload all color images to product gallery

3. Name images consistently (e.g., "red-shirt.jpg", "blue-shirt.jpg")

4. Add plugin code with proper variant mapping

pluginProductSwatches({
    'variants': {
        'Red': ['red-shirt.jpg', 'red-shirt-back.jpg'],
        'Blue': ['blue-shirt.jpg', 'blue-shirt-back.jpg'],
        'Green': ['green-shirt.jpg', 'green-shirt-back.jpg']
    }
});

Why did my swatches stop working after a Squarespace update?

Common post-update issues:

• Product page structure changed - Plugin selectors may be outdated

• Files need re-uploading - Update may have affected file system

• Code injection modified - Verify injection is still correct

• New product features conflict - Squarespace updates may interfere

Troubleshooting steps:

1. Clear all caches

2. Re-upload plugin files

3. Check browser console for errors

4. Test with simple product setup

5. Contact support for updated plugin version

E-commerce Platform Limitations

Why doesn't the plugin work with my Print on Demand products?

POD-specific challenges:

• Too many variants can overwhelm the plugin

• Size/color combinations create complex matrices

• Limited image control in POD platforms

Solutions:

• Focus on color variants only (ignore size variations for swatches)

• Simplify variant structure to essential options

• Use representative images rather than exact variant images

• Consider color-only swatches without image switching

Is it possible to have the color variants display on the category/collection pages or inside a summary block?

Limitation: Possible only in a product block, not on category/collection pages or summary blocks.

Alternative approaches:

• Use product blocks within layout sections

• Create category pages with individual product blocks

• Consider custom development for collection page swatches

Customization & Appearance

Can I use custom color images instead of solid color circles?

Method 1: Upload swatch images

pluginProductSwatches({
    'swatchImages': {
        'Red': '/s/red-swatch.jpg',
        'Blue': '/s/blue-swatch.jpg',
        'Green': '/s/green-fabric-swatch.jpg'
    }
});

Method 2: CSS background images

.product-swatch[data-variant="Red"] {
    background-image: url('/s/red-texture.jpg');
    background-size: cover;
}
.product-swatch[data-variant="Blue"] {
    background-image: url('/s/blue-fabric.jpg');
    background-size: cover;
}

Can I change the size and shape of the color swatches?

Complete swatch styling:

.product-swatch {
    width: 40px !important;
    height: 40px !important;
    border-radius: 50% !important; /* Circles */
    /* border-radius: 0 !important; /* Squares */
    /* border-radius: 8px !important; /* Rounded squares */
    border: 2px solid #ddd !important;
    margin: 0 5px 5px 0 !important;
    cursor: pointer !important;
    transition: all 0.2s ease !important;
}

.product-swatch:hover {
    transform: scale(1.1) !important;
    border-color: #333 !important;
}

.product-swatch.active {
    border-color: #000 !important;
    box-shadow: 0 0 0 2px rgba(0,0,0,0.3) !important;
}

Is there a way to keep the color variant as a circle and the size as a square/rectangular button?

To make the size as a square/rectangular button, use the Scope option and set the item border radius to 0%:

How do I disable the clickable functionality and make swatches display-only?

Display-only swatches:

.product-swatch {
    pointer-events: none !important;
    cursor: default !important;
}

Or modify plugin configuration:

pluginProductSwatches({
    'clickable': false,
    'displayOnly': true
});

Advanced Features

Dim Buttons if Selected Variant is Unavailable or Sold Out

Add this code after the plugin code in Code Injection:

<!-- Dim Buttons if Selected Variant is Unavailable or Sold Out -->
<!-- Author: Dmitry Kiselyov @_dmitrykiselyov -->
<style>
.c-swatches__button.is-unavailable {
    opacity: 0.25;
}
</style>
<script>
function dimButtonsIfVariantUnavailableOrSold(){
    var productVariants=document.querySelector(".product-variants"),
        buttons=[].slice.apply(document.querySelectorAll(".c-swatches__button"));
    if(!productVariants||!buttons.length)return null;
    function isVariantInStock(){
        return productVariants.getAttribute("data-variant-in-stock")
    }
    function buttonsHandler(button){
        button.classList.remove("is-unavailable"),
        !isVariantInStock()&&button.classList.contains("is-active")&&button.classList.add("is-unavailable")
    }
    buttons.forEach((function(button){
        button.addEventListener("click",(function(){
            buttons.forEach(buttonsHandler)
        }))
    }))
}
document.addEventListener("DOMContentLoaded",dimButtonsIfVariantUnavailableOrSold);
window.addEventListener("mercury:load",dimButtonsIfVariantUnavailableOrSold);
</script>
<!-- end Dim Buttons if Selected Variant is Unavailable or Sold Out -->

Deselect First Variant

To deselect the first variant, add this code after the plugin code:

<!-- Plugin Swatches - Deselect First Variant -->
<script>
function deselectFirstVariant(){
    [].slice.call(document.querySelectorAll(".view-item .c-swatches")).forEach((function(item){
        var thumbnail=document.querySelector(".ProductItem-gallery-thumbnails-item");
        thumbnail&&thumbnail.click();
        var button=item.querySelector(".c-swatches__button.is-active");
        button&&button.classList.remove("is-active");
        var select=document.querySelector('select[data-variant-option-name="'+item.getAttribute("data-option")+'"]');
        select&&(select.selectedIndex=0,select.dispatchEvent(new Event("change")))
    }));
    [].slice.call(document.querySelectorAll(".view-item .variant-option-title")).forEach((function(title){
        title.removeChild(title.children[0])
    }))
}
setTimeout(deselectFirstVariant,150);
</script>
<!-- end Plugin Swatches - Deselect First Variant -->

Display Variant Names Above Swatches

To display variant names (Color:, Size:) above the swatches, add this code to Custom CSS:

/* Display Variant Name */
.ProductItem-details .variant-option-title {
    display: block;
}

Troubleshooting & Common Issues

The swatches appear but clicking them shows "undefined" in the URL. How do I fix this?

Variant name mismatch issue:

• Check Commerce settings - Note exact variant names (case-sensitive)

• Verify plugin configuration - Names must match exactly

Common mismatches:

• "red" vs "Red" (capitalization)

• "Light Blue" vs "LightBlue" (spaces)

• "Navy Blue" vs "Navy" (shortened names)

Debugging steps:

// Add to console to check variant names
console.log(document.querySelectorAll('[data-variant]'));

Swatches work on desktop but not mobile. What should I do?

Mobile-specific issues:

• Touch events vs click events

• Swatch size too small for fingers

• Mobile browser limitations

Mobile-optimized CSS:

@media screen and (max-width: 767px) {
    .product-swatch {
        width: 44px !important; /* Larger for touch */
        height: 44px !important;
        margin: 0 8px 8px 0 !important;
        /* Touch-friendly spacing */
    }
    
    .product-swatch-container {
        padding: 10px 0 !important;
    }
}

Touch-friendly JavaScript:

// Handle both click and touch events
$('.product-swatch').on('click touchend', function(e) {
    e.preventDefault();
    // Swatch functionality here
});

I can see the swatches but they don't change the product image. Why?

Image switching troubleshooting:

• Verify image uploads - All variant images in product gallery

• Check image names - Must match plugin configuration exactly

• Test image paths - Ensure images are accessible

• Browser cache - Clear cache after changes

• JavaScript errors - Check console for errors

Quick test:

// Test if images exist
var img = new Image();
img.onload = function() { console.log('Image loaded'); };
img.onerror = function() { console.log('Image failed to load'); };
img.src = '/s/your-variant-image.jpg';

Performance & Optimization

Swatches load slowly or cause performance issues. How do I optimize?

Performance optimization:

• Compress images before uploading

• Limit number of variants to essential options

• Use appropriate image sizes (not oversized images)

Preload critical images:

<link rel="preload" as="image" href="/s/red-variant.jpg">
<link rel="preload" as="image" href="/s/blue-variant.jpg">

Lazy load non-critical variants:

pluginProductSwatches({
    'lazyLoad': true,
    'preloadFirst': 3 // Preload first 3 variants only
});

Configuration Examples

Basic Configuration

pluginProductSwatches({
    'variants': {
        'Red': ['red-product.jpg'],
        'Blue': ['blue-product.jpg']
    }
});

Advanced Configuration

pluginProductSwatches({
    'variants': {
        'Red': ['red-shirt.jpg', 'red-shirt-back.jpg'],
        'Blue': ['blue-shirt.jpg', 'blue-shirt-back.jpg']
    },
    'swatchImages': {
        'Red': '/s/red-swatch.jpg',
        'Blue': '/s/blue-swatch.jpg'
    },
    'clickable': true,
    'displayOnly': false,
    'lazyLoad': true,
    'preloadFirst': 2
});

For additional support, ensure your variant names match exactly between Commerce settings and plugin configuration. Check the browser console for JavaScript errors and verify all plugin files are properly uploaded.