SwatchKit documentation

Requirements #

SwatchKit is compatible with WooCommerce's High-Performance Order Storage (HPOS). It works with classic and block themes.

Installation #

From your WordPress dashboard

1. Go to Plugins → Add New Plugin and search for SwatchKit.
2. Click Install Now, then Activate.
3. That's it — every variation dropdown on your store is now a swatch. Settings live under WooCommerce → Swatches.

Manual upload

1. Download swatchkit-variation-swatches.zip from WordPress.org.
2. Go to Plugins → Add New Plugin → Upload Plugin, choose the zip, and click Install Now.
3. Activate the plugin.

Quick start #

With the defaults, every attribute becomes a button (label) swatch the moment you activate. To get colour or image swatches:

1. Pick a type for the attribute. Go to Products → Attributes, click Edit on an attribute (for example Color), set Type to Color, Image or Label, and save.
2. Give each term its colour or image. Click Configure terms next to the attribute and edit each term. Colours use a colour picker; images use the Media Library.
3. Tune the look. Open WooCommerce → Swatches. Change shape, size and stock behaviour and watch the live preview update before you save.

Attribute types #

The type is set per attribute under Products → Attributes → Edit. It decides how that attribute's swatches look everywhere on the store.

Colour swatches #

Edit a term under Products → Attributes → Configure terms and set Swatch colour with the colour picker, or type a hex value such as #1e3a8a. Leave it empty to set it from the term name.

The checkmark on a selected colour swatch automatically turns black or white, depending on how light the colour is, so it stays visible on white, yellow and black swatches alike.

Image swatches #

1. Set the attribute's type to Image under Products → Attributes.
2. Open Configure terms, edit a term, and click Choose image under Swatch image.
3. Pick or upload an image in the Media Library and click Use this image. The preview appears next to the button; Remove clears it.
4. Save the term. The term list shows a thumbnail in the Swatch column so you can check every term at a glance.

Image tips

• Use square images of at least 100 × 100 px. Swatches are small, so a close crop of the pattern works better than a photo of the whole product.
• Keep Image quality on Gallery thumbnail (the default). It is the smallest generated size and loads fastest.
• Set Image fit to Fit (no crop) for logos or cut-out product shots that must not be cropped.
• Turn on image tooltips (General → Tooltip content → Image) to show a larger preview on hover. Its size is set by Tooltip image size.
• A term with no image still renders as a selectable swatch showing its name, so shoppers can buy it before you add images.

All image options are in Style → Image swatches. Image swatches are part of the free plugin.

Size / label swatches #

Label swatches show the term name as a button. They need no configuration — the term's name is the label. Control the text size with Label font size in Style. Term order follows the order you set on the attribute (drag to reorder under Configure terms).

WooCommerce's built-in Color / Image type #

WooCommerce 10.9 added its own Color / Image attribute type. If you already use it, SwatchKit reads the colours and images you set there — nothing to re-enter. On those attributes the term screen shows WooCommerce's own fields, and SwatchKit adds only the preview column, so there is one place to edit each value.

SwatchKit adds what the built-in type does not do: size/label swatches, out-of-stock handling, tooltips, shop-page swatches, classic-theme support and correct availability above 30 variations.

Per-product overrides #

Sometimes one product needs to look different: a Color attribute that should be images on a patterned product, or pill-shaped sizes on a single item.

1. Edit the product and open Product data → Advanced.
2. In the SwatchKit panel, each variation attribute has a type and a shape dropdown.
3. Leave them on Inherit global to follow the store-wide settings, or choose a value to override just this product.

Stock & availability #

As a shopper picks options, SwatchKit marks every other swatch as available, out of stock, or unavailable — and it stays correct at any number of variations.

Choose how each state looks under Stock settings: cross out, blur, dim, hide, or (for out of stock) leave as-is. The settings page shows a small preview of each effect on its card.

Why it works above 30 variations

By default WooCommerce stops sending variation data to the page once a product has more than 30 variations. Most swatch plugins lose track of stock at that point and show everything as available. SwatchKit keeps a compact availability index for each product — a 1,200-variation product needs about 3 KB — so availability is always known, with no AJAX requests while shoppers click.

The index rebuilds automatically when you save a product or variation, when stock changes (including orders and refunds), when you edit attribute terms, and after imports. You never need to rebuild it by hand; Tools → Clear swatch cache is there if you ever want to.

Shop & category pages #

Turn on Archive / Shop → Show swatches on shop and category pages to show swatches under each variable product in the shop, category and tag archives. Shop-page swatches are free.

• Placement — after the title, after the price, or after the button.
• Attributes to show — pick one (usually colour) to keep product cards tidy.
• Every variable product on the page is loaded in a single database query, however many products the page shows.

Add to cart from the shop page and a +N more limit are Pro features.

Settings reference #

All settings are at WooCommerce → Swatches. You can also reach them from the Settings link under SwatchKit on the Plugins screen. Changes appear in the live preview before you save; press Ctrl/⌘ + S to save. If you try to leave with unsaved changes, the page asks first.

Settings marked Pro are visible but locked in the free plugin.

General #

Style #

Shape and size

Borders and colours

Image swatches

Interactions

Stock #

Archive / Shop #

Advanced #

Tools #

• Clear swatch cache — empties the availability index. It rebuilds automatically, one product at a time, as pages are viewed.
• System status — versions, number of indexed products, object cache, active theme, whether WooCommerce's built-in Color/Image type is on, and any other swatch plugins that are active. Include this when you contact support.

Themes & builders #

SwatchKit never overrides WooCommerce template files. It swaps the dropdown through WooCommerce's own filter and keeps the original <select> in the page, hidden, as the source of truth. That is why it works with most themes without any theme-specific code.

• Themes: any theme that uses WooCommerce's standard variation form — classic or block. Because nothing is overridden, the theme's own layout and styles stay in charge.
• Page builders: Elementor (including the editor preview) and Bricks.
• Quick view, AJAX load-more and infinite scroll: new product forms are detected automatically — no setup.
• Translation: WPML and Polylang. Swatch data is cached per language.

Caching & performance #

• Storefront script: about 3 KB gzipped, with no jQuery or other libraries. Stylesheet: about 1.3 KB.
• Scripts and styles load only on product pages (and shop pages when shop swatches are on).
• Swatches are rendered on the server at their final size, so the page does not shift as it loads.
• Page caches (WP Rocket, LiteSpeed Cache, W3 Total Cache, Cloudflare) need no exclusions — swatch state is computed in the browser from data already in the page.
• Object caches (Redis, Memcached) are used automatically and flushed correctly when WooCommerce flushes its own cache.

Accessibility #

• Swatches are real buttons in a radio group. Tab reaches each attribute once; ← → ↑ ↓, Home and End move between swatches.
• Screen readers hear the attribute name, the term name and its state, for example “Blue (out of stock)”. State is never shown by colour alone.
• A visible focus ring that themes can't accidentally remove, plus Windows High Contrast support.
• Animations turn off for visitors who have “reduce motion” enabled.
• Right-to-left languages are supported.

Switching from another plugin #

1. Keep the old plugin installed for now but deactivate it. Don't delete it — some plugins remove their data on delete.
2. Activate SwatchKit. Your attributes, terms and variations are WooCommerce data and stay untouched.
3. Set each attribute's type (Attribute types) and check your colours and images under Configure terms.
4. When everything looks right, delete the old plugin.

Tools → System status lists any other swatch plugin that is still active.

Markup & CSS variables #

This markup is stable from 1.0.0. Changing it would be a breaking change, so it is safe to style against.

<div class="swk-swatches swk-swatches--color" role="radiogroup"
     aria-labelledby="swk-label-pa_color"
     data-attribute="pa_color" data-type="color"
     data-oos="cross" data-unavailable="dim"
     style="--swk-size:40px;--swk-radius:6px">
  <button type="button" class="swk-swatch swk-swatch--color is-selected"
          role="radio" aria-checked="true" tabindex="0"
          data-value="red" style="--swk-swatch-color:#e02b2b">
    <span class="swk-swatch__inner" aria-hidden="true"></span>
    <span class="screen-reader-text">Red</span>
  </button>
</div>

• Type modifiers: swk-swatch--color, --image, --label.
• State classes: is-selected, is-out-of-stock, is-unavailable, is-hidden.
• data-oos and data-unavailable carry the stock-behaviour settings.

CSS custom properties

Restyle swatches by redefining variables — no !important needed.

/* Bigger, fully round colour swatches with a black ring */
.swk-swatches--color {
  --swk-size: 48px;
  --swk-radius: 50%;
  --swk-selected-color: #111;
}

Theme support #

Themes can opt out of SwatchKit's stylesheet or tooltips:

add_action( 'after_setup_theme', function () {
    add_theme_support( 'swatchkit', array(
        'stylesheet' => false, // the theme styles swatches itself
        'tooltip'    => false, // the theme has its own tooltips
    ) );
} );

PHP hooks #

Filters

Actions

Examples

// Keep the dropdown for the "Engraving" attribute.
add_filter( 'swatchkit_attribute_type', function ( $type, $taxonomy ) {
    return 'pa_engraving' === $taxonomy ? '' : $type;
}, 10, 2 );

// No swatches on products in the "Gift cards" category.
add_filter( 'swatchkit_should_render', function ( $render, $product ) {
    return has_term( 'gift-cards', 'product_cat', $product->get_id() ) ? false : $render;
}, 10, 2 );

// Always use circles, whatever is saved.
add_filter( 'swatchkit_settings', function ( $settings ) {
    $settings['shape'] = 'circle';
    return $settings;
} );

JavaScript API #

The storefront script exposes a small API on window.SwatchKit.

SwatchKit.on( 'change', function ( detail ) {
  console.log( detail.attribute, '→', detail.value );
} );

// After injecting product HTML yourself:
document.dispatchEvent( new CustomEvent( 'swatchkit:refresh' ) );

Because SwatchKit updates WooCommerce's hidden <select> and fires a normal change event, WooCommerce's own events (found_variation, reset_data) keep working for your code.

REST API #

All routes require the manage_woocommerce capability and a REST nonce or application password.

Troubleshooting #

FAQ #

Free vs Pro #

Everything in the free plugin stays free. Pro adds features on top; it never takes anything away.

See Pro plans from WooCommerce → Swatches → Get Pro.

Getting support #

• Free plugin: the WordPress.org support forum.
• Pro customers: priority support from your account at modinatheme.com.

To get a fast answer, include the output of WooCommerce → Swatches → Tools → System status, your theme name, and a link to the product page.

Enjoying SwatchKit? A review on WordPress.org helps other store owners find it.