Using swatches

This walkthrough takes a fresh install to working swatches on a variable product, then explains exactly how they behave on the storefront.

1. Pick the store default

Open WooCommerce → Swatch, keep Enable swatches on, and set the default swatch type. Most stores leave it on Button / label and switch the Colour attribute to colour dots on its own screen, but if most of your variation attributes are colours, set the default to Colour.

2. Choose the type per attribute

Go to Products → Attributes and open each global attribute you use on variable products:

• For Colour, set the type to Colour so each term renders as a dot.
• For Size, Material and similar, use Button / label so each term renders as a readable pill.

3. Assign colours and labels to terms

Open the attribute’s terms (Configure terms). For a colour attribute, set a hex colour on each term, for example #1a1a1a for Black, #c0392b for Red. For a button/label attribute, leave the label blank to use the term name, or set a custom label when you want shorter text on the pill.

4. Confirm on a variable product

Open a variable product that uses the attribute. The dropdown is replaced by a radiogroup of swatches. Selecting one:

• sets the value on the original (hidden) <select> and fires its change event,
• so WooCommerce updates the price, stock and add-to-cart button exactly as the dropdown would,
• and marks invalid combinations: as you choose one attribute, swatches in another attribute that cannot pair with it are disabled.

Re-clicking the active swatch clears the selection (the same as choosing the dropdown’s blank option). A disabled swatch is dimmed and struck through with a diagonal line, so the unavailable state is never signalled by colour alone.

Keyboard and screen-reader behaviour

Each attribute’s swatches are a single radiogroup:

• Tab moves focus to the group; arrow keys (and Home/End) move between swatches; Space/Enter selects.
• The focused swatch shows a visible focus-visible ring, so keyboard users always see where they are.
• Each swatch carries the term name as an aria-label, so screen-reader users hear Red, Large and so on, not just “button”. Button swatches show the label as visible text; colour dots carry it as screen-reader text.

When swatches fall back

Swatch never forces a broken control. An attribute with no type set and no usable per-term data, and any custom (non-taxonomy) attribute, keeps WooCommerce’s standard dropdown. A colour attribute with no colours set falls back too. The rest of the variations form keeps working, so you can configure attributes gradually.

Extending the output (developers)

After Swatch builds an attribute’s swatch group it passes the markup through a filter before appending it to the dropdown:

add_filter( 'swatch/swatch_group_html', function ( string $html, string $attribute, array $args ): string {
    // $attribute is the taxonomy/name; $args are WooCommerce's dropdown args.
    return $html;
}, 10, 3 );

This is the same hook Swatch Pro uses to swap in image swatches. Swatch registers no shortcodes, the swatches appear automatically wherever WooCommerce renders the variations form.

Performance and accessibility notes

The front-end is vanilla JavaScript, loaded defer in the footer, listening to WooCommerce’s own variation events, no jQuery is added by Swatch and no external request is made. CSS and JS load only on single product pages. Sizes are CSS custom properties, the swatches reserve their space up front, and the design respects prefers-reduced-motion, so swatches add no layout shift.