Image Swatches

Image Swatches present choices as small clickable thumbnail images. Only one image can be selected at a time (single choice). Use them when a photograph or texture preview communicates a choice better than a plain color or text label.

---

When to Use

• Fabric or material texture previews
• Pattern or print selection (plaid, stripe, polka-dot)
• Finish sample photos (polished, brushed, matte)
• Style preview thumbnails where a photo explains better than words

---

Configuration Settings

When you add an Image Swatch field in the Addon Builder, you can configure the following inputs across different sections:

General Settings

• Label: The main heading shown above the swatches. Used to identify the field group in the cart and order details.
• Description: Additional helper text shown below the swatches. Useful for providing instructions.

Options Configuration

Within the main Options block, you define the actual image choices by clicking the Add Choice button. For each choice card in the list, you have access to inline inputs and an expandable settings panel.

Inline Editor (Always Visible):

• Drag Handle: Use the left-side grip icon to drag and drop choices to reorder how they appear on the frontend.
• Image Uploader: Click the image icon (or existing thumbnail) to open the WordPress Media Library and select/upload the swatch image.
• Label: The primary text shown next to the swatch on the frontend, and in the cart (e.g. Herringbone).
• (System Value): Smart Product Options and Addons automatically generates a system-friendly value behind the scenes by lowercasing your Label and replacing spaces with underscores.

Expanded Settings Panel: Click the downward chevron icon on the right side of any choice card to expand its advanced settings:

• Price Type: Choose how this specific image choice is priced (None, Flat Fee, Percentage, or Formula). Read the Pricing Guide →
• Price Amount / Formula Expression: Appears if a price type is selected. Enter the monetary surcharge or the dynamic math formula.
• Weight (kg): Enter a numeric value to add physical shipping weight to the cart when this option is ticked.
• Stock Tracking: A toggle that, when enabled, opens the per-option inventory controls. Read the Stock Linking Guide →
  • Select Pool: Choose which Global Stock Item to link this image choice to.
  • Reduction Mode: Choose how stock is deducted (Per Item Quantity, Per Line Item, or Formula).

Validation

• Field is Required: A checkbox toggle. When enabled, the customer is forced to click and select an image thumbnail before they are allowed to add the product to their cart.

---

Display Style

You can choose how swatches are presented visually on the frontend product page:

• Swatch Only: Renders only the thumbnail box. The choice name appears as a tooltip on hover.

  

• Swatch + Label: Renders both the thumbnail box and its descriptive text label.

  

---

Swatch Appearance (Global Settings)

Note: The physical shape and size of the image swatches are controlled globally across your entire store to ensure design consistency. Go to WooCommerce → Settings → Products → Options to configure:

• Image Swatch Size: Default is 64px.
• Image Swatch Roundness: Change the border-radius. Use 50% for circular thumbnails, or 4px for gently rounded corners.

---

Pricing Logic

Smart Product Options and Addons choice fields (like Image Swatches) do not support field-level pricing. Instead, pricing is configured individually per option within the General tab under the Options Configuration block.

Option-Level Pricing: Set specific price surcharges on individual choices (e.g., "+$5.00 for Premium Pattern") by expanding the choice card and selecting a Price Type:

• Price Type: (None, Flat Fee, Percentage, or Math Formula).
• Price Amount / Formula Expression: The fee applied when this specific option is selected.

Master the Pricing Engine

Smart Product Options and Addons includes multiple pricing strategies, including dynamic math formulas. We've created a dedicated guide to explain all of them in detail.

Read the Ultimate Pricing Guide →

---

Conditions

Open the Conditions tab to dynamically show or hide this swatch group based on what the customer has selected in other fields.

Available Inputs:

• Enable Conditional Logic: Toggle to turn conditions on or off.
• Action: Choose whether to Show or Hide this field when conditions are met.
• Match Type: Choose ALL (every rule must match) or ANY (at least one rule must match).
• Rules: Define the specific field to watch, the comparison operator, and the value to check against.

Example: Show the "Lining Fabric Pattern" image swatches only if the customer selects "With Lining" from a previous Dropdown.

Learn More About Conditions

Conditional logic lets you build dynamic, branching forms that adapt as the customer interacts. See the full list of operators and examples in our detailed guide.

Read the Field Conditions Reference →

---

Stock

Because an Image Swatch field contains multiple distinct options, stock is linked per option instead of for the whole field.

Open the Stock tab to link individual patterns/materials to their respective inventory pools.

Available Inputs:

• Enable Stock Management: Toggle to activate inventory tracking.
• Per-Option Links: You will see a row for every image you uploaded. For each row, you can select an existing Global Stock Item and define the Reduction Mode (Per Item Quantity, Per Line Item, or Formula).

Option-Level Stock Visibility

If you enable Stock Tracking inside any individual choice card under the General tab, it activates option-level stock. When this happens, the field-level Stock tab shown above is automatically hidden in the backend to prevent conflicting inventory rules.

Example: Link the "Herringbone" fabric choice to an inventory item tracking your bolts of Herringbone cloth.

Global Stock Management

Smart Product Options and Addons lets you share stock pools across multiple options and products, complete with cart-reservation to prevent overselling.

Read the Guide: Linking Options to Stock →

---

Example & Frontend Display

To see how this comes together, let's look at a common scenario: Selecting a wood finish for custom furniture. You want customers to pick one wood texture, and you charge an extra $50.00 specifically if they choose the "Premium Walnut" finish.

You would configure the Image Swatch field like this:

• Label: Wood Finish
• Display Style: Swatch + Label
• Option 1: Label Classic Oak, Image oak-texture.jpg, Price Type None
• Option 2: Label Distressed Pine, Image pine-texture.jpg, Price Type None
• Option 3: Label Premium Walnut, Image walnut-texture.jpg, Price Type Flat Fee, Price Amount 50.00

Frontend Product Page View: With those settings, here is how the field renders on your product page for customers to interact with:

When a customer clicks an image thumbnail and adds the product to their cart, Smart Product Options and Addons validates that the submitted value exactly matches one of the allowed options you defined, preventing forged submissions.

Cart & WooCommerce Order View: The field label and the text label of the chosen image (not the image file itself) will appear clearly on the cart page, checkout, and in your WooCommerce admin order screen exactly like this:

Wood Finish:   Premium Walnut