Product Configurator Image Mapping: The Image Follows the Chosen Option

About the Extension

Add-on plugin – requires the Product Configurator (SwpProductOptionsSix). This plugin works exclusively as an extension of the base plugin Product Configurator (SwpProductOptionsSix). Without the installed, active, and separately purchased base plugin, this plugin has no function.

A customer builds a sofa in dark green velvet and keeps looking at a photo of the grey fabric one. They click through the options, the picture never moves, and in the end they email you to ask what the thing actually looks like. You answer that question several times a week. Plenty of customers never ask at all and buy somewhere else.

The problem

A configurator sells combinations that do not exist as separate articles. Your image gallery has never heard of those combinations, so it shows whatever sits on the product, no matter what the customer clicks. The usual workaround is a separate article for every colour and every finish. Now you maintain twenty articles instead of one, every price change runs twenty times, and the configurator has lost its point.

The solution

This plugin ties images to configurator options. Open a product in the administration, click "Assign images" in the product configurator area, pick an image from your media library and tick the options it belongs to. Save, done. When a customer selects exactly those options in your shop, the plugin swaps the gallery image. No page reload, no jump, no loading bar.

What's in it for you

Customers see what they are building. Instead of imagining the result, they look at it. That removes the most common pre purchase question and makes the choice easy to commit to.

One article stays one article. No dummy variants created just to park an image somewhere. Prices, stock and copy stay in a single place.

Mapping takes minutes, not days. Pick an image, tick the options, save. No theme surgery, no developer hours, no extra interface to maintain.

The swap covers the whole gallery. Main image, thumbnail and the picture inside the zoom window change together, so a customer who zooms in still sees the finish they selected.

You decide per sales channel. The plugin settings carry a switch for each channel. Your trade shop can run without image swapping while your consumer shop uses it.

A broken mapping never takes a page down. If loading the mappings fails, the plugin writes the error to its own log channel and the product page keeps rendering, simply with the default image.

How the plugin works

Every mapping holds three things: the product, one image, and the option combination that image belongs to. You can create as many mappings per product as you need, each with its own combination. All mappings of a product sit in a list on the product itself, where you edit or delete them. Deleting always asks first.

In the shop the plugin compares the customer's current selection with the stored combinations. If one matches, the assigned image appears. If none matches, the gallery falls back to the product's default image. There is no half matching image, and therefore no broken one either.

This works on the product detail page and in Shopping Experiences that build a product page with an image gallery. Images come from your normal media library, and you can upload a new one straight from the mapping dialogue.

Typical use cases

Furniture and upholstery. An armchair in eight fabrics. The customer picks the fabric and the photo shows that exact cover, not a colour swatch sitting next to an unrelated picture.

Printed clothing and merchandise. A shirt in five colours with two print positions. Photograph the combinations that actually sell, let the rest fall back to the default image.

Doors, windows and ironmongery. Stainless steel or brass handle, glass or timber panel. With building components the picture often decides whether someone orders online or phones you first.

Equipment with fitting options. A machine with or without the extra head, long cable or short one. One image per configuration settles the question of what arrives in the box.

Technical facts for your IT team

The plugin runs on Shopware 6.7 with PHP 8.2 or newer.

Add-on plugin – requires the SwpProductOptionsSix product configurator from version 6.7.12 and only works together with it.

Mappings live in a dedicated database table. Shopware tables are neither modified nor extended. When a product page is built, the plugin loads that product's mappings in a single database query, capped at 500 records per product so one outlier cannot slow a page down. The image swap itself happens in the browser and triggers no further request to the server.

The plugin sends no data to external servers. It processes no personal data and sets no cookies. Permissions ride on the existing product roles: reading, creating, editing and deleting mappings are tied to product privileges, so you do not need to build a separate role. Errors go to the plugin's own log channel. Uninstalling follows the Shopware standard: tick the option to keep user data and the table and settings stay in place, otherwise the plugin removes both. The interface and help texts are available in English, German and Dutch.

To be honest

Without the SwpProductOptionsSix configurator this plugin does nothing. It is an extension for it, not a configurator of its own and not a replacement for Shopware variants. It does not create images either: whatever the customer should see has to exist as a photo or a rendering and has to be mapped by you. If you are after a live 3D preview that calculates colour and material in the browser, this is the wrong plugin. And the swap hooks into the image gallery of the Shopware storefront. If your theme replaces that gallery with its own build, test the behaviour on a staging instance before you go live. The quickest way to know is to install the plugin and map a single product.

Legal notice

We accept no liability for legal requirements. Please check the use of this plugin with a qualified legal advisor.