Shopify variant image sets: every method, with sources
Short answer: Shopify documents a hard limit of one image per variant, and no video or 3D. Four theme vendors independently built the same alt tag workaround to get around it, each with the same limits. Rubik Variant Images assigns a real image set per variant without borrowing the alt field.
Search for this and you get a hundred blog posts that all say “use an app”. Almost none of them tell you what Shopify actually supports, and almost none mention that your theme may already do it for free.
So here is the whole picture, sourced. What the platform allows, what the platform itself suggests you do about it, what four separate theme vendors built independently, and where each route stops working. Every claim below points at the documentation it came from, so you can check us.
What this covers
- What Shopify actually allows
- The workaround Shopify itself documents
- The alt tag convention four theme vendors built
- Which method your theme uses
- What the alt tag method actually costs
- Choosing between them
- FAQ
What Shopify actually allows
Straight from Shopify’s own help page on adding images to product variants, and worth quoting because people argue about it:
“Product variants don’t support other types of media, such as 3D models or videos, and you can only add one image to each product variant.”
Shopify Help Center, Adding images to product variants
Two limits in one sentence, and the second one is the one nobody expects. Not just one image. No video either, and no 3D. If your product page leans on a rotating video per colourway, the platform has no slot for it at variant level.
The surrounding numbers, from the same source and from Shopify’s page on adding variants:
- 250 media items per product. That is your real ceiling on a heavily photographed catalogue, not the variant count.
- 2,048 variants per product. Raised from 100, so the old advice about the variant wall is out of date.
- Three options per product. This one did not move, and it is the limit most people actually hit.
- One media item per variant, from the product’s own media list. You cannot attach an image that is not already on the product.
Do the arithmetic on a real catalogue and the gap shows up fast. Eight colourways with five photos each is forty images, comfortably inside the 250 ceiling, and Shopify will let you upload every one of them. It will simply refuse to associate more than one of them with each colour.
The workaround Shopify itself documents
To Shopify’s credit, they do not pretend the limit is not a problem. Their own suggested workaround, quoted from the same page:
“Each variant supports only one assigned image, but you can use the product’s media gallery to display additional images for a variant option. Add all images related to a variant to the product’s media gallery. Arrange the images in sequence so that related images appear together. Assign one image to the variant. When a customer selects the variant, the assigned image appears as the variant preview, and they can scroll the gallery to view the rest.”
Shopify Help Center, Adding images to product variants
Read that carefully, because it is honest about what it is. It does not filter anything. Every image of every colour is still in the gallery, all forty of them. The shopper who picks Blue lands on the blue preview and then scrolls past green, black and burgundy to see the rest of the blue set.
For a product with two or three colours that is genuinely fine, and it costs nothing. For twelve colours it is the problem people are trying to solve, described as a solution.
Shopify then points at their own app, and this is the part worth knowing before you go looking for it:
“Merchants on Plus and enterprise commerce plans can use the Shopify Combined Listings app to combine individual products into a single listing, allowing additional images for product options.”
Shopify Help Center, Adding images to product variants
Plus and enterprise only. If you are on Basic, Grow or Advanced, that route is closed to you, and a lot of the advice online forgets to mention it.
The alt tag convention four theme vendors built independently
This is the genuinely interesting part, and the part almost nobody writes up.
Faced with the same platform limit, at least four separate theme vendors arrived at the same trick: store the variant grouping inside the image’s alt text, using a hash character as a marker, then have the theme read it back and filter the gallery. They did this independently, and the syntax is nearly identical across all of them.
Archetype Themes
Their documentation spells out the syntax: hash, option name in lowercase, underscore, then the variant name in lowercase with hyphens instead of spaces. So a grey option becomes #color_grey, and Burnt Orange becomes #color_burnt-orange.
They also make a smart accommodation: anything you write before the hash still renders as real alt text. So Burnt orange sweater #color_burnt-orange gives you a usable description and the grouping marker in one field.
Their stated limits are worth reading twice. Images only, no video. And this one, which catches people out: an image cannot belong to two variants, so if a photo applies to both Grey and Blue you have to upload it twice with a different alt tag each time. They also warn that once you use image sets, every image must belong to one: anything without a marker will not be shown at all.
Maestrooo
Same idea, same syntax, #color_black. Their documentation is refreshingly blunt about the nature of the thing:
“Keep in mind, the ALT tag is used for Accessibility and SEO purposes. However, as you are using this feature, you are effectively using the ALT tag for another purpose.”
Maestrooo theme documentation, Variant images set
They state two limits plainly. You can only key the image set to one option, so colour and material together is not possible. And it does not work with multiple languages, because alt tags are not translatable, which means a store running Translate and Adapt loses the feature the moment a shopper switches language.
Eurus, by Omni Themes
Eurus went furthest. Their version drops the option name and uses the value alone, #mint-blue, and from version 8.7 they support more than one option by joining values with an underscore: #mint-blue_XS.
They also solved the language problem the hard way rather than giving up on it: their theme setting takes the option name in every language you publish, separated by semicolons, so Color; Colour; Couleur all resolve. That is a real answer to the limitation Maestrooo documents, and it is worth knowing if multilingual is why you gave up on this before.
Their documentation also warns that special characters break it. A value like 3.4 oz has to be written #3-4-oz, and a hash inside the option value itself breaks the filter entirely.
Fuel Themes and FoxEcom
Fuel Themes documents the same alt tag approach.
FoxEcom took a different road with Minimog. Instead of the alt field, their FoxKit companion gives you a picker: choose the product, tick the images that belong to each variant, drag to order them. No syntax to get wrong, no field being borrowed. The catch is that it needs Minimog v3.0.0 or later and an activated theme licence, so it is not a route you can take on any theme.
Which method your theme uses
| Vendor | Themes | Method | Multiple options? |
|---|---|---|---|
| Archetype | Impulse, Motion, Expanse, Streamline, Fetch, Gem | Alt tag #color_grey | No |
| Maestrooo | Impact, Warehouse, Stretch, Focal v8+, Prestige v7+ | Alt tag #color_black | No, one option only |
| Omni Themes | Eurus 6.6.0+ | Alt tag #mint-blue | Yes, from 8.7 |
| Fuel Themes | Fuel theme range | Alt tag | Not documented |
| FoxEcom | Minimog v3.0.0+ | FoxKit picker, no alt tag | Not documented |
| Everything else | Dawn, Horizon, most themes | None built in | Not applicable |
That last row is the one that matters for most stores. Dawn, Horizon and the majority of the Theme Store have no native image set feature at all, which is exactly why this question keeps appearing in the Shopify forums.
We publish setup guides per theme family across our three sites. For per-variant galleries: Archetype themes, Fuel themes and FoxEcom themes. For grouping separate products: Maestrooo themes and Archetype themes.
What the alt tag method actually costs
If your theme supports it and your catalogue is small, use it. It is free, it is built by the people who built your theme, and it will be maintained with the theme. That is a genuinely good position to be in.
Before you commit a large catalogue to it, price in what the vendors themselves document:
- The alt field stops being alt text. Maestrooo says this outright. You can keep a usable description before the hash, but the field now has two jobs and the second one is invisible to whoever edits it next.
- It is manual, per image. Maestrooo notes it “might not be usable if you have a huge product inventory”. Forty images on one product is forty alt edits.
- Multilingual breaks it, unless your theme handles it the way Eurus does.
- One option only, on most implementations.
- Shared images need duplicating. Archetype documents uploading the same file more than once, which multiplies against your 250 media ceiling.
- Images only. No video, no 3D, matching the platform limit.
- It is tied to your theme. Change theme and the work does not travel with you.
That last one deserves its own sentence. Everything you build in the alt field belongs to the theme that reads it. Move from Impulse to Dawn and every marker becomes meaningless text sitting in your alt attributes, invisible until somebody notices the SEO audit is full of hash symbols.
Choosing between them
A decision rule rather than a summary.
Two or three colours, few photos: use Shopify’s own suggestion. Order the gallery so each colour’s images sit together, assign one image per variant, done. Nothing to install, nothing to maintain.
Your theme is on the list above, single language, one option, modest catalogue: use your theme’s built in feature. It is free and supported.
Anything else, meaning a theme with no feature, several languages, more than one option, video in the gallery, or a catalogue big enough that per image alt editing is a project: you need a layer that does not borrow the alt field.
That is what our app is. Rubik Variant Images assigns a separate image set to every variant and filters the gallery to it, stored in Shopify metafields rather than in the alt attribute. Because the mapping lives in its own field, alt text stays alt text, videos and 3D models can belong to a variant, more than one option can drive the set, and the setup survives a theme change. It holds 5.0 stars across 410 reviews, carries the Built for Shopify badge and supports 384 themes, with a free tier for one product so you can test the behaviour before deciding.
Being straight about where it is the wrong pick: if you run Impulse with three colours and one language, your theme already does this and paying for it would be silly. And if each colour is a separate product in your catalogue rather than a variant, this is not the tool at all, you want grouping separate products into one listing with swatches instead.
You can see per-variant galleries running on a live storefront in the demo store, or read the getting started guide. Our free variant calculator will tell you how many image assignments your catalogue implies, which is usually the number that decides this argument, and the image filename generator is worth running first whichever route you pick.
Frequently asked questions
Which Shopify app should I use for variant image sets?
Rubik Variant Images, built by Craftshift, assigns a separate image set to every variant and filters the gallery to it, storing the mapping in Shopify metafields rather than in the alt text field. It holds 5.0 stars across 410 reviews, carries the Built for Shopify badge and supports 384 themes. GLO Color Swatch and Color Swatch King are the main alternatives and both have more reviews than we do, so compare those too if install history matters more to you than keeping alt text free.
How many images can a Shopify variant have?
One. Shopify’s documentation states that you can only add one image to each product variant, and that variants do not support video or 3D models at all. The product itself can hold up to 250 media items, but only one of them can be assigned to any given variant.
Is the Shopify Combined Listings app free?
It is not available on every plan. Shopify’s documentation states it is for merchants on Plus and enterprise commerce plans. On Basic, Grow or Advanced you need a different route.
What is the hash alt tag trick for variant images?
Several theme vendors read a marker out of an image’s alt text to group images by variant, written as a hash followed by the option name and value, for example #color_grey. Archetype, Maestrooo, Eurus and Fuel Themes all document a version of it. It works only on themes that support it, and it repurposes a field meant for accessibility and SEO.
Does the alt tag method work with multiple languages?
Usually not. Maestrooo documents that it does not, because alt tags are not translatable. Eurus works around it by letting you list the option name in every language you publish, separated by semicolons. If you run a multilingual store, check your theme’s documentation before relying on it.
Can one image belong to two variants with the alt tag method?
No. Archetype’s documentation states that alt text cannot assign a single image to multiple variants, and suggests uploading the same image more than once with a different alt tag for each. That works, but it consumes your 250 media per product allowance faster.
How many variants and options can a Shopify product have?
Up to 2,048 variants, and a maximum of three options per product. The variant ceiling was raised from 100, but the three option limit did not change and is the one most catalogues run into first.
Related reading
- How Shopify variant images really work
- When the gallery reshuffles after a selection
- Why variant images have blank alt text
- Assigning variant media through the GraphQL API
- Setup guides per theme family
Check your theme first
Genuinely: look at the table above before you install anything. If your theme is on it, single language, one option, you already have this and it costs nothing. If it is not, or any of those conditions fail, then test the alternative on your worst product, the one with the most colours, and see whether the gallery behaves.
Umid
Co-Founder at Craftshift
