Table of Contents

1. Introduction
2. Getting Started
3. Admin Settings Overview (3 Tabs)
4. General Settings Tab
5. Global Customizations Tab
6. Shop/Archive Page Tab
7. Changing the Display Type
8. Swatch Display Types Explained
9. Out-of-Stock Behavior
10. Adding Colors & Images to Attributes
11. Single Product Page Behavior
12. Shop/Archive Page Behavior

1. Introduction

Variation Swatches is a feature of the Woo Essential plugin that replaces the default WooCommerce variation dropdown selectors with beautiful, interactive visual swatches. Instead of choosing product options (like color or size) from plain dropdown menus, your customers can click on color circles, image thumbnails, styled buttons, and more.

Key Benefits

• Replace boring dropdowns with visual color, image, and button swatches
• Works on both single product pages and shop/archive pages
• AJAX add-to-cart on shop pages — no page reload needed
• Smart out-of-stock handling — unavailable options are visually disabled
• Fully customizable — colors, sizes, borders, tooltips, and more
• Responsive and mobile-friendly design
• Keyboard accessible for improved usability

2. Getting Started

Prerequisites

• WordPress 5.0 or higher
• WooCommerce 5.0 or higher (active and configured)
• Woo Essential plugin installed and activated
• At least one variable product with product attributes and variations configured

How to Enable Variation Swatches

1. Log in to your WordPress admin dashboard.
2. Navigate to Woo Essential in the left sidebar menu.
3. Click on Extensions.
4. Find "Variation Swatches" and turn the toggle ON to enable it.
5. The page will reload. A new "Variation Swatches" menu item will appear in the Woo Essential sidebar.
6. Click "Variation Swatches" to access the settings page.

Note: The Variation Swatches menu item only appears after you enable the extension from the Extensions page. If you don't see it, make sure the toggle is ON and the page has reloaded.

3. Admin Settings Overview

The Variation Swatches settings page is organized into 3 tabs. Each tab groups related settings together for easy navigation.

Path: Woo Essential → Variation Swatches

After making changes on any tab, click the Save button at the bottom of the settings panel to apply.

4. General Settings Tab

Path: Woo Essential → Variation Swatches → General Settings

This is the primary tab where you enable the feature, choose how swatches look, and configure out-of-stock behavior.

Enable/Disable Toggles

Display Type

Choose the default swatch style used across your store. This is set via radio buttons with 4 options:

•  — Text labels in rectangular buttons (default)Button
•  — Circular text buttons with radio-style indicatorRadio
•  — Styled custom dropdownSelect
•  — Swatches with checkmark overlay on selectionCheckbox

Important: Color and Image swatch types are determined automatically from the attribute term metadata. If a term has a color value set, it renders as a color swatch. If it has an image, it renders as an image swatch. The Display Type setting controls the fallback for terms without color/image metadata. See Section 7 for a step-by-step guide on changing the display type.

Disabled Attribute Style

When "Disable Out of Stock" is ON, this controls how unavailable swatches appear:

•  (default) — Semi-transparent with a diagonal lineBlur with Cross
•  — Semi-transparent onlyBlur
•  — Completely hidden from displayHide

Color Settings

Each color setting has a reset button to clear the custom value and revert to the default.

5. Global Customizations Tab

Path: Woo Essential → Variation Swatches → Global Customizations

This tab controls the visual appearance of swatches — dimensions, borders, labels, and tooltips. Settings here apply globally across both single product and shop/archive pages unless noted otherwise.

Label Settings

Swatch Dimensions

You can set different swatch sizes for single product pages and shop/archive pages. Shop page swatches are smaller by default to fit within product cards.

Border Settings

Tooltip Settings

Tooltips appear when customers hover over a swatch, showing the attribute value name (e.g., "Red", "Large"). Optionally, image swatches can show an image preview in the tooltip.

Tip: Enabling "Image Preview on Tooltip" is useful for fabric/pattern attributes — customers see a larger preview on hover without clicking.

6. Shop/Archive Page Tab

Path: Woo Essential → Variation Swatches → Shop/Archive Page

These settings apply only to swatches on shop pages, category pages, tag pages, and other WooCommerce archive pages.

Label Display

Positioning & Alignment

Visibility & Filtering

7. Changing the Display Type

The display type determines how variation swatches are visually presented to your customers. Here is a step-by-step guide to change it.

Step-by-Step: Change the Default Display Type

Path: Woo Essential → Variation Swatches → General Settings → Display Type

1. Go to your WordPress admin dashboard.
2. Navigate to Woo Essential → Variation Swatches in the sidebar.
3. You will land on the settings page. Make sure the "General Settings" tab is selected (it is the first tab and selected by default).
4. Scroll down to the "Display type" section.
5. You will see 4 radio button options: Button, Radio, Select, Checkbox.
6. Click on the option you want to use as your default display type.
7. Click the Save button at the bottom of the page.
8. Visit your store to see the updated swatch style.

How Display Type Interacts with Attribute Metadata

The display type you choose acts as the default fallback. However, if an attribute term has specific metadata set, that takes priority:

Example: You set Display Type to "Radio". Your product has two attributes: Color (with color metadata set on terms) and Size (no metadata). The Color attribute will render as color circle swatches. The Size attribute will render as Radio-style circular buttons.

Step-by-Step: Customize Swatch Look & Feel

Path: Woo Essential → Variation Swatches → Global Customizations

After choosing a display type, customize its visual appearance:

1. Switch to the "Global Customizations" tab.
2. Adjust Swatch Dimensions (width/height) for single product and shop pages separately.
3. Set Border Radius: 100% for circular swatches, 0% for square, or anything in between.
4. Set Border Width and Border Color to match your theme.
5. Configure Tooltip settings (enable/disable, position, colors).
6. Click Save.

Step-by-Step: Customize Colors for Swatches

Path: Woo Essential → Variation Swatches → General Settings → Color Settings

1. Stay on the "General Settings" tab.
2. Scroll to the color settings at the bottom of the tab.
3. Set Attribute Background Color — the background for text-based swatches (Button, Radio, Checkbox).
4. Set Attribute Font Color — the text color inside swatches.
5. Set Attribute Active Background Color — the background when a swatch is selected.
6. Set Attribute Cross Color — the color of the diagonal line on disabled swatches.
7. Click Save.

Tip: Each color field has a color picker and a reset button. Click reset to revert to the default value.

8. Swatch Display Types Explained

A detailed look at each display type and when to use it.

Button (Default)

•  Rectangular text labels with a borderAppearance:
•  Border highlight / background color changeSelection indicator:
•  Size (S, M, L, XL), Material, Weight, or any text-based attributeBest for:
•  [ S ] [ M ] [ L ] [ XL ]Example:

Radio

•  Circular text buttons with a radio-dot style indicatorAppearance:
•  Filled background on selectionSelection indicator:
•  Size selectors, pattern types, any attribute where a "picked one" feel is desiredBest for:
•  ( S ) ( M ) ( L ) — selected one fills with colorExample:

Checkbox

•  Swatches with a checkmark overlay when selectedAppearance:
•  Visible checkmark on color/image swatches; background change on text swatchesSelection indicator:
•  Attributes where a clear "checked" confirmation is desiredBest for:

Select (Custom Dropdown)

•  A beautifully styled custom dropdown replacing the plain WooCommerce selectAppearance:
•  Color dot preview for color attributes, hover effects, scrollable options listFeatures:
•  Attributes with many options (10+) where swatches would take too much spaceBest for:

Note: On single product pages, setting the display type to "Select" will keep the original WooCommerce dropdown since it is already a select. The custom dropdown is primarily useful on shop/archive pages.

Color (Automatic)

•  Circular filled color blocks showing the actual colorAppearance:
•  Setting a color value on the attribute term (see Section 10)Triggered by:
•  If no color metadata is set, the system tries to resolve color from the term name (e.g., "Red" becomes #FF0000)Fallback:
•  40+ common colors — red, blue, green, yellow, orange, purple, pink, black, white, gray, navy, teal, maroon, olive, coral, and moreRecognized names:

Image (Automatic)

•  Small image thumbnails representing each optionAppearance:
•  Setting an image on the attribute term (see Section 10)Triggered by:
•  Fabric patterns, textures, material previewsBest for:
•  Use small, square images (around 100x100px) for best resultsTip:

9. Out-of-Stock Behavior

Path: Woo Essential → Variation Swatches → General Settings → Disable Out of Stock

Variation Swatches intelligently handles out-of-stock variations to give customers a clear visual indication of availability.

How It Works

When "Disable Out of Stock" is enabled (ON by default), the system checks all variations of a product. An attribute value (e.g., "Red") is marked as disabled ONLY if every single variation that includes it is out of stock.

Example: Your product has Red/Small, Red/Medium, and Red/Large variations. If Red/Small and Red/Large are out of stock but Red/Medium is still available, the "Red" swatch stays active — because there is at least one in-stock variation with that color.

Disabled Swatch Styles

Path: Woo Essential → Variation Swatches → General Settings → Disabled Attribute Style

Tip: The cross line color can be customized via the "Attribute Cross Color" setting under General Settings → Color Settings.

10. Adding Colors & Images to Attributes

For color and image swatches to work, you need to assign color values and/or images to your WooCommerce product attribute terms.

Setting Up Color Swatches

Path: Products → Attributes → [Your Attribute] → Configure Terms → Edit Term

1. Go to Products → Attributes in WooCommerce.
2. Click on the attribute you want to configure (e.g., "Color").
3. Click "Configure terms" to see all values (Red, Blue, Green, etc.).
4. Click "Edit" on a term (e.g., "Red").
5. Look for the "Swatch Color" field and enter a hex color code (e.g., #FF0000) or use the color picker.
6. Click "Update" to save the term.
7. Repeat for each attribute term that should display as a color swatch.

Auto Color Resolution: If you don't set a color value, the system will try to automatically resolve the color from the term name. It recognizes 40+ common color names including: red, blue, green, yellow, orange, purple, pink, black, white, gray/grey, navy, teal, maroon, olive, coral, and more.

Setting Up Image Swatches

Path: Products → Attributes → [Your Attribute] → Configure Terms → Edit Term

1. Go to Products → Attributes in WooCommerce.
2. Click on the attribute you want to configure.
3. Click "Configure terms".
4. Click "Edit" on a term.
5. Look for the "Swatch Image" field and click "Upload/Add Image" to select an image from the Media Library or upload a new one.
6. Click "Update" to save the term.

Tip: Use small, square images (around 100x100px) for best results. Larger images will be scaled down to the configured swatch dimensions.

11. Single Product Page Behavior

Path: Woo Essential → Variation Swatches → General Settings → Enable for Product Page

When enabled, swatches replace the default WooCommerce dropdown selects on individual product pages. All existing WooCommerce variation functionality is fully preserved.

What Changes vs. Default WooCommerce

How It Works Behind the Scenes

• The native WooCommerce dropdown is hidden but remains in the page for compatibility
• Swatch clicks automatically update the hidden dropdown value
• WooCommerce's built-in variation JS handles all price updates, image swaps, and stock display
• The "Clear" / "Reset" link works normally — it resets both swatches and the hidden dropdown

12. Shop/Archive Page Behavior

Path: Woo Essential → Variation Swatches → General Settings → Enable for Shop/Archive

When enabled, variation swatches appear directly on product cards in the shop page, category pages, tag pages, and other WooCommerce archive pages. Customers can select a variation and add to cart without visiting the product page.

What Gets Added to Each Product Card

• Swatches for each variation attribute (Color, Size, etc.)
• A quantity input field (appears after selecting a valid variation)
• An Add to Cart button (appears after selecting a valid variation)

AJAX Add to Cart

The Add to Cart button works via AJAX — the page does not reload. After a successful add, the cart widget/icon in your header updates automatically with the new item count and total. This provides a seamless shopping experience.

How the Selection Flow Works

1. Customer browses the shop page and sees swatches under each variable product.
2. Customer clicks on swatch(es) to select their desired variation (e.g., Red + Medium).
3. Once all required attributes are selected, the quantity input and Add to Cart button appear.
4. Customer adjusts quantity if needed and clicks Add to Cart.
5. The item is added via AJAX — no page reload. Cart updates in the header.

Configuring Shop Page Swatches

Path: Woo Essential → Variation Swatches → Shop/Archive Page

Use the Shop/Archive Page tab to fine-tune the experience:

•  (e.g., "Color:", "Size:")Show/hide attribute labels
•  (e.g., "Selected: Red")Show/hide the selected value text
•  left, center, or right within the product cardAlign swatches
•  before or after the default add-to-cart areaPosition swatches
•  with a "+N more" overflow indicatorLimit visible items

Infinite Scroll / AJAX-Loaded Products

If your theme or a plugin loads more products via AJAX (infinite scroll, "Load More" button, etc.), Variation Swatches automatically re-initializes on newly loaded products. No additional configuration is needed.

Appendix: Complete Settings Reference

All settings organized by their admin tab.

General Settings Tab

Global Customizations Tab

Shop/Archive Page Tab