Introduction
Getting Started
Admin Settings Overview (3 Tabs)
General Settings Tab
Global Customizations Tab
Shop/Archive Page Tab
Changing the Display Type
Swatch Display Types Explained
Out-of-Stock Behavior
Adding Colors & Images to Attributes
Single Product Page Behavior
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

Log in to your WordPress admin dashboard.
Navigate to Woo Essential in the left sidebar menu.
Click on Extensions.
Find “Variation Swatches” and turn the toggle ON to enable it.
The page will reload. A new “Variation Swatches” menu item will appear in the Woo Essential sidebar.
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

Tab	What It Controls
General Settings	Enable/disable swatches, choose display type, out-of-stock behavior, swatch colors
Global Customizations	Swatch dimensions, borders, label font size, label position, tooltip settings
Shop/Archive Page	Label visibility, selected value display, alignment, position, max items, catalog mode

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

Setting	Default	Description
Enable for Product Page	OFF	Show swatches on single product pages, replacing the default WooCommerce dropdown selects
Enable for Shop/Archive	OFF	Show swatches on shop pages, category pages, tag pages, and other archive pages with AJAX add-to-cart
Clear on Reselect	OFF	When ON, clicking an already-selected swatch deselects it. When OFF, clicking the same swatch does nothing
Disable Out of Stock	ON	Visually disable swatches for attribute values where all variations are out of stock

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

Setting	Default	Description
Attribute Background Color	Transparent	Background color for text-based swatches (Button, Radio). Use the color picker or enter a hex value.
Attribute Font Color	Theme default	Text color inside swatches
Attribute Active Background Color	Theme default	Background color when a swatch is selected/active
Attribute Cross Color	#1a1a2e	Color of the diagonal cross line on disabled (out-of-stock) swatches

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

Setting	Default	Description
Label Font Size	14px	Font size for attribute labels (e.g., “Color:”, “Size:”)
Label Position	Stacked	How labels are positioned relative to swatches: Stacked (above), Inline (beside), or None (hidden)

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.

Setting	Default	Context
Swatch Width (Single Product)	32px	Single product page only
Swatch Height (Single Product)	32px	Single product page only
Swatch Width (Shop/Archive)	24px	Shop and archive pages only
Swatch Height (Shop/Archive)	24px	Shop and archive pages only

Border Settings

Setting	Default	Description
Border Radius	100%	Controls roundness: 100% = circle, 0% = square. Accepts values 0–100.
Border Width	1px	Thickness of the swatch border in pixels
Border Color	Theme default	Color of the swatch border (hex value, with color picker)

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.

Setting	Default	Description
Enable Tooltip	ON	Show or hide tooltips on hover
Tooltip Background Color	#1a1a2e	Background color of the tooltip box
Tooltip Font Color	#ffffff	Text color inside the tooltip
Tooltip Position	Top	Show tooltip above (Top) or below (Bottom) the swatch
Tooltip Font Size	12px	Size of the tooltip text
Hide Tooltip Arrow	OFF	Remove the small arrow pointer from the tooltip
Image Preview on Tooltip	OFF	Show an image thumbnail inside the tooltip for image-type swatches

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

Setting	Default	Description
Show Swatches Label	OFF	Display the attribute name above swatches (e.g., “Color:”, “Size:”)
Show Selected Attribute	OFF	Display the currently selected value as text (e.g., “Selected: Red”)
Variation Label Separator	:	The character placed after the attribute label (e.g., “Color:” vs “Color -“)

Positioning & Alignment

Setting	Default	Options
Swatch Alignment	Left	Left, Center, Right — horizontal alignment of swatches within the product card
Swatch Position	Before	Before Add to Cart button, After Add to Cart button — where swatches appear relative to the default add-to-cart area

Visibility & Filtering

Setting	Default	Description
Maximum Attribute Items	Empty (show all)	Limit the number of visible swatches. Overflow shows a “+N more” indicator. Example: set to 5 to show 5 swatches + “+15 more” if 20 options exist.
Display Catalog Mode	All OFF	Checkboxes for: First Attribute, Brand, Color, Pattern, Size. Controls which attributes appear as swatches in catalog view.
Show on Filter Widget	OFF	Enable swatches in filter/layered navigation widgets

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

Go to your WordPress admin dashboard.
Navigate to Woo Essential → Variation Swatches in the sidebar.
You will land on the settings page. Make sure the “General Settings” tab is selected (it is the first tab and selected by default).
Scroll down to the “Display type” section.
You will see 4 radio button options: Button, Radio, Select, Checkbox.
Click on the option you want to use as your default display type.
Click the Save button at the bottom of the page.
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:

Attribute Term Has…	Swatch Rendered As	Display Type Setting Used?
Color value (dnwooe_color)	Color swatch (circular color block)	No — color overrides the default
Image (dnwooe_image)	Image swatch (thumbnail)	No — image overrides the default
Neither color nor image	Uses the Display Type setting	Yes — Button, Radio, Select, or Checkbox

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:

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

Step-by-Step: Customize Colors for Swatches

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

Stay on the “General Settings” tab.
Scroll to the color settings at the bottom of the tab.
Set Attribute Background Color — the background for text-based swatches (Button, Radio, Checkbox).
Set Attribute Font Color — the text color inside swatches.
Set Attribute Active Background Color — the background when a swatch is selected.
Set Attribute Cross Color — the color of the diagonal line on disabled swatches.
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

Style	Visual Effect
Blur with Cross (Default)	Swatch becomes semi-transparent (50% opacity) with a diagonal line through it
Blur Only	Swatch becomes semi-transparent (50% opacity) without any cross line
Hide	Swatch is completely hidden from the display

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

Go to Products → Attributes in WooCommerce.
Click on the attribute you want to configure (e.g., “Color”).
Click “Configure terms” to see all values (Red, Blue, Green, etc.).
Click “Edit” on a term (e.g., “Red”).
Look for the “Swatch Color” field and enter a hex color code (e.g., #FF0000) or use the color picker.
Click “Update” to save the term.
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

Go to Products → Attributes in WooCommerce.
Click on the attribute you want to configure.
Click “Configure terms”.
Click “Edit” on a term.
Look for the “Swatch Image” field and click “Upload/Add Image” to select an image from the Media Library or upload a new one.
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

Feature	Default WooCommerce	With Variation Swatches
Attribute Selection	Plain dropdown (<select>)	Visual swatches (color, image, button, etc.)
Selection Indicator	Dropdown shows selected text	Highlighted swatch + optional text label
Out-of-Stock Options	Grayed-out dropdown options	Blurred, crossed-out, or hidden swatches
Price/Image Updates	Built-in WooCommerce JS	Same — fully preserved
Add to Cart	Built-in WooCommerce button	Same — fully preserved
Reset/Clear	WooCommerce reset link	Same — clears both swatches and hidden dropdown

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

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

Configuring Shop Page Swatches