dfvariantswatch — Variant photo swatches & stock

Overview

dfvariantswatch replaces the combination dropdowns on PrestaShop product pages with clickable visual swatches (photos, colors or text), previews the variant in the main gallery on hover, and shows each variant’s stock right on the swatch.

The module works by enhancing PrestaShop’s native widgets via JavaScript: it does not replace any theme template, which is what keeps it compatible with Classic, Hummingbird and most premium themes.

Installation

1. Back office → Modules → Module Manager → Upload a module
2. Drag and drop the dfvariantswatch.zip archive and click Install
3. Click Configure to open the settings

Installation creates the df_variant_swatch table, the img/dfvariantswatch/ image folder and the default configuration values. No theme modification is required.

How swatches are chosen

For each attribute, the module picks the swatch source in this order of priority:

1. Image uploaded in the back office for that attribute (Per-attribute swatches tab)
2. Hex color code defined in the back office
3. Automatically derived image from the first combination using that attribute
4. Native PrestaShop color of the attribute (the group’s color field)
5. Text chip with the attribute name

The undifferentiated-group safeguard

Automatic derivation is only kept when images actually differ between the group’s attributes, or when the group is flagged as a color group in PrestaShop. In practice: on a product with a Size group (S, M, L, XL) where all combinations share the same photos, sizes stay as text chips instead of showing the same photo four times.

Configuration

General settings

• Enable module — turns off front rendering without uninstalling
• Swap gallery on hover — variant preview when hovering a swatch
• Show stock badge — availability state below each swatch
• Hide out-of-stock variants — completely hides exhausted swatches instead of striking them through
• Shape — round, square or pill; Size in pixels
• Low-stock threshold — below it, the badge switches to the low-stock state
• Stock labels — all three texts are customizable and translatable via Localization → Translations
• Data loading mode — Inline (recommended) or AJAX, see below
• Groups not rendered as swatches — selected groups keep their native widget

Per-attribute swatches

This tab lists every attribute group in the store. For each value you can upload an image (jpg, png, webp or gif, 2 MB maximum, 200 by 200 pixels recommended) or enter a color code in #RRGGBB format, preview the current swatch and delete an existing one.

Data loading modes

Inline (default, recommended): variant data is embedded in the page at render time. No AJAX call on load, immediate swatch display, maximum robustness.

AJAX: data is fetched after page load. Reserve this mode for stores behind aggressive full-page caching where displayed stock freshness matters more than display speed.

Keyboard accessibility

The selector implements the WAI-ARIA radiogroup pattern: Tab focuses the group’s selected variant (a single tab stop per group), arrow keys navigate and select within the group with wrap-around while skipping unavailable variants, Space or Enter confirms the focused swatch. States are announced to screen readers via aria-checked and tooltips respect prefers-reduced-motion.

CSS customization

The exposed CSS variables let you adjust the appearance from your child theme’s CSS without touching the module:

.dfvs-swatch {
    --dfvs-size: 56px;   /* swatch size */
}
.dfvs-swatch.dfvs-active {
    box-shadow: 0 0 0 2px #b8860b; /* active variant ring */
}

To disable the hover preview on a specific product, add an element carrying the data-dfvs-disable-hover attribute in the product template.

Troubleshooting

Swatches do not appear

• Check that the module is enabled in its configuration
• Open the browser console: the module traces its steps with the [dfvariantswatch] prefix — you will see the number of rendered groups or the reason nothing rendered
• The product must have combinations; a simple product shows nothing, which is expected

Sizes show as text, not photos

That is the safeguard’s expected behavior: the group’s values share the same combination photos. Upload dedicated images per size in the Per-attribute swatches tab if you want visuals (for instance sizing pictograms).

The native block reappears after a click

The module re-applies hiding after every PrestaShop AJAX update. If a heavily customized theme bypasses the standard events, contact support with the URL of the affected product page.

Uninstall

Uninstalling removes the module’s table, the images uploaded to img/dfvariantswatch/ and every configuration key. Your combination photos are of course untouched.