Configuration

Swatch is configured in two places: the global settings page for the store-wide default, and the attribute and term screens where you set the type per attribute and the colour or label per term. The global screen is deliberately small, most of the real configuration lives with each attribute, so it stays correct as your catalogue grows.

Global settings

Open WooCommerce → Swatch. There are two settings, stored in the swatch_settings option.

Enable swatches

The master switch, on by default. When off, every variable product falls back to WooCommerce’s standard <select> dropdowns and no swatch CSS or JavaScript is enqueued, nothing is lost, the look just reverts to default. Your per-term colours and labels stay saved for when you turn it back on.

Default swatch type

The type used by any attribute that has no explicit type of its own:

• Colour, round colour dots, filled with the hex colour you set per term.
• Button / label, pills showing the term’s label (or its name when no custom label is set).

An attribute overrides this on its own screen, so the default is just the starting point. Note: a Colour default applied to an attribute with no colours set still falls back to the dropdown, so this choice never breaks a product.

Per-attribute type

Go to Products → Attributes and open a global attribute. The Swatch type selector offers Use plugin default, Button / label, or Colour. This is stored per taxonomy in the swatch_attribute_types option, so a Colour attribute can render as dots while Size renders as pills in the same store. Custom (product-level) attributes have no taxonomy and always use the plugin default.

Per-term colour and label

On a global attribute’s term add/edit screen you set, as term meta:

• Swatch colour, a native colour picker (<input type="color">). Saved through sanitize_hex_color; an invalid or empty value is removed, not stored. Used by colour-type swatches as the dot fill.
• Swatch label, optional short text for a button/label pill, stored as swatch_label. Leave it blank to use the term’s own name.

Both fields are capability-gated to manage_woocommerce and nonce-checked on save.

How the settings combine

When a variable product renders, each attribute resolves its type (its own, else the default), then reads each term’s colour or label to build the swatches. A colour attribute where no term has a colour produces no usable swatches, so Swatch returns WooCommerce’s untouched dropdown for that attribute. A half-configured attribute never breaks the page.

Theming with CSS

The storefront styles are built on --swatch-* custom properties, size, gap, radius, border and the selection accent, so you can re-theme swatches from your theme stylesheet without fighting markup or specificity. The accent inherits your theme’s link colour where one is exposed. Focus-visible rings, sufficient contrast, dark-mode colours and prefers-reduced-motion handling are built in and need no configuration.

Storage and cleanup

Settings live in swatch_settings; per-attribute types in swatch_attribute_types; per-term values in the swatch_color and swatch_label term meta. Everything stays in your own database, Swatch contacts no external service.