Where do Showcase theme swatch image files go?

Clean Canvas now documents uploading them through the Shopify admin under Content, then Files. Older theme generations, and many other Shopify themes still, looked for the file in the theme's own Assets folder instead, which is why much of the older advice on this topic tells you to edit theme files.

Can the Showcase theme show a different set of photos per color without an app?

Partly. Clean Canvas documents a product page setting that only shows media associated with the selected variant, where the association comes from the order of the media in the admin rather than from an assignment. The documented limit is that it applies to a single variant option per product template, so a product where two options both change the photos is not covered.

Rubik Variant Images Guides, Shopify Tips & Tutorials

Why are my variant swatch images blank on the Showcase theme?

Q: My Shopify option value has a slash in it. Why is the swatch blank?

Under a filename-based swatch system, a slash cannot survive. A filename cannot contain one, so the name the theme derives and the file you upload can never agree. The fixes are to rename the option value to something like Black and White, or to use a method that stores the swatch against the variant rather than matching it by name, at which point the characters in the value stop mattering.

August 4, 2026

Why are my variant swatch images blank on the Showcase theme?

Short answer: Showcase resolves a theme swatch by turning your option value into a filename and loading that file. Miss by one character and the circle renders empty, silently. Rubik Variant Images, built by Craftshift, attaches a swatch image to every variant as a metafield instead, so there is no filename to get wrong. 5.0 stars, 420 reviews.

Blank Showcase theme variant swatches are almost never a broken theme. They are a name that did not match, and the reason it is so maddening to debug is that nothing anywhere tells you that.

Think about what the browser is actually doing. It asked for an image, got a 404, and moved on. A 404 on an image is not an exception. It does not stop the page, it does not appear in your theme editor, it does not warn you in the admin. You get a correctly sized, correctly positioned, perfectly styled circle containing absolutely nothing, and the only place the failure is visible is a network tab you probably never opened.

That silence is the whole problem. So this post is mostly about making the failure visible, and then about deciding whether you want to keep maintaining filenames at all.

Showcase has three swatch systems, not one

This is the piece almost every answer skips, and it is why two people with the identical symptom get contradictory advice.

Showcase is a Clean Canvas theme, Theme Store ID 677, and Clean Canvas’s own swatch documentation describes three separate ways a swatch can get its appearance. They do not share a data source. They do not fail the same way.

Method	Where the data lives	How it fails
Shopify swatches	Shopify option value data, driven by the product category	Missing category or wrong option name, so no swatch data exists
Theme swatches, variant image method	The featured image on each variant	Variant has no image assigned, so nothing to draw
Theme swatches, color list method	A list in the theme settings, mapping a name to a hex code or a file	Name does not match the option value, or the file is not found

Blank circles, as opposed to no circles at all, almost always mean the third one. The theme found a swatch to render, sized it, styled it, and then had nothing to put inside. If you were getting no swatch row whatsoever, you would be looking at the first two rows instead.

The filename lookup, in detail

Here is the mechanism, and once you see it the whole class of bug becomes obvious.

A swatch image is not attached to anything. There is no field on the variant that points at it, no reference stored anywhere, no relationship in the database. The theme takes the text of your option value, transforms it into a filename by a fixed rule, and asks for a file with that name. If the file exists, you get a swatch. If it does not, you get a hole.

Clean Canvas documents the transformation plainly: name each file to match the handle of the variant color title, replace spaces with a dash, keep the filename lowercase, remove any special characters, and use only the Latin alphabet. Their own worked example is a variant called Fire Engine Red mapping to fire-engine-red.png. Their own warning example is even better, because it is the one that catches European stores: waldgrün.png has to be renamed waldgrun.png.

Two things changed over the years and both matter for what you should be typing.

Where the file lives has moved. Older theme generations, and plenty of themes still in the wild today, looked for the swatch inside the theme’s own Assets folder, which is why so much advice on this topic tells you to edit theme files. Clean Canvas now documents uploading them through the Shopify admin under Content, then Files. If you are following a three-year-old forum answer that tells you to drop PNGs into Assets, that is probably why nothing is resolving.

And from Showcase 10.0.0 the derivation became explicit rather than automatic. Instead of the theme guessing your filename from the option value, the color list setting takes entries in the form ColorName:filename.png, with Clean Canvas’s example being Red:red.png. That is a genuine improvement, and I will say why in a moment, but it also means half the advice online now describes a version you are not running. Check your theme version before trusting any of it.

Everything that quietly breaks the match

In rough order of how often we see each one.

A capital letter. The option value is Navy Blue and the file is Navy-Blue.png. The lookup wants navy-blue.png. Some hosting setups are case insensitive and some are not, which is exactly why this one produces the maddening “it works on my machine” pattern.
A space that stayed a space. navy blue.png instead of navy-blue.png. The upload accepts it happily.
An accent or a non-Latin character. Waldgrün, Café au Lait, Rosé. Clean Canvas tells you to strip these, and the reason is that the transformation removes them, so the derived name never matches a file that kept them.
A slash in the option value. Black/White is extremely common and it is the nastiest of the set, because you cannot even name a file with a slash in it. The slash becomes a separator or vanishes, and whatever you upload will not be what is asked for.
The wrong extension. The documentation says PNG. You exported JPG because the source photo was a JPG. Same name, different file, no match.
A double extension from the export. navy-blue.png.png. Operating systems hide extensions by default, so this one is invisible in your file browser and obvious in the URL.
Trailing whitespace in the option value itself. A value pasted from a spreadsheet carries a trailing space more often than anyone expects, and it changes the derived name.
The value drifted. You renamed Navy to Navy Blue three months ago on 40 products. The file did not rename itself.

Look at that list again and notice what every entry has in common. Not one of them is a coding mistake. They are all typing. A system whose failure mode is “you typed it slightly differently in two places, three weeks apart, and nothing will tell you” is a system that will keep failing, forever, on every new color you add. That is my honest opinion of the whole approach, and the 10.0.0 change to explicit Red:red.png entries is Clean Canvas quietly agreeing: at least now both halves of the pair sit next to each other in one setting where you can see them.

If you are about to rename a batch of files, run the values through our free image filename generator first and paste the output rather than typing it. It applies the same lowercase, dash and strip-accents transformation, which removes the human step that causes most of the list above.

Sixty seconds to prove which one you have

Stop guessing. Get the actual URL the theme asked for and the answer falls out.

Open a product page with a blank swatch on your live storefront.
Right click the empty circle and choose Inspect.
Look for an img tag or a background-image in the highlighted element. Read the URL.
Copy that URL into a new tab and load it.

Now you know. If the URL loads your swatch image, the problem is CSS and not the file, so go look at sizing, overflow or a color that matches the background. If it 404s, compare the filename in that URL against the file you uploaded, character by character, and one of the eight causes above will be staring at you. If there is no image reference at all, the theme never found a swatch entry, which means you are on the wrong swatch method for the data you have.

That last case sends you back to the table at the top. Our general Shopify color swatches not working guide covers the causes that are not theme specific, and there is a longer treatment of the filename mechanism across themes in the assets folder filename trap on craftshift.com.

The newer path: option value swatches

Shopify has been moving swatch data out of themes entirely, and it is worth understanding because it fails in a completely different way.

Assign a product category, name the option Color, and the option values themselves carry a swatch: a color or an image, set in the admin, exposed to any theme through Shopify’s Liquid swatch object. No filename. No convention. The value and its appearance are the same record, so they cannot drift apart, and the same data feeds collection page filters, which the theme-side methods never do.

When this one fails you get no swatches rather than blank ones, and the cause is almost always upstream: no product category assigned, or the option is named Colour or Shade rather than Color, or the values were never given a swatch. Different symptom, different fix. If your theme supports it, it is the better of the two theme-side routes by a distance, and we walk through setting it up in how to add image swatches in Shopify.

The other blank: media that will not filter

Worth separating, because people arrive here with two different blanks and call them the same thing. A blank swatch is a missing tile. A gallery that will not narrow is something else entirely.

Showcase does ship a native answer for the second one. Clean Canvas documents a product page setting called “Only show media associated with the selected variant”, and the association is made by ordering rather than by assignment: you group the product media in the admin so that all the Navy photos sit together, all the Rust photos sit together, and the theme infers the boundaries. Clean Canvas is upfront that Shopify’s admin does not support assigning multiple images to a single variant, which is why the workaround exists at all.

It also comes with a limit worth knowing before you build around it: the grouping applies to one variant option per product template. One. So a product with Color and Material where both change the photos is out of scope, and so is any store that needs one template to handle products that group by different options.

Order-based grouping is a reasonable design and it costs nothing, so try it first. Its weakness is the same as the filename’s: the relationship is implied rather than stored, so reordering the gallery, or an app that touches media order, silently regroups everything. Related background sits in how many images per variant Shopify allows and variant images not showing.

Removing the filename from the equation

Everything above shares one root cause: the swatch and the variant are connected by a convention instead of a reference. Fix that and this entire category of bug stops existing.

Showcase is in our supported theme config, which carries 386 entries, and Clean Canvas themes are among the more predictable ones to integrate with because the codebase is mature and consistent across their catalog. We wrote up the family in Rubik Variant Images on Clean Canvas themes.

If you would rather stop maintaining a naming convention across a growing catalog, Rubik Variant Images attaches a swatch image or color directly to each variant and writes it to two Shopify metafields, craftshift.swatch_color and craftshift.swatch_image. Per variant, not per option value, so Navy on the parka and Navy on the tee can be different tiles. Rename the option value tomorrow and nothing breaks, because nothing was ever matched by name. Free for one product, then $25 a month for 100.

A few details that matter on a theme like Showcase specifically. The resolver has a fallback chain: custom swatch image, then custom swatch color, then the variant image, then the product image, so a variant you forgot does not render a hole, it renders the next best thing available. Because those are ordinary metafields you can fill them from Shopify’s bulk editor rather than clicking through an app screen, which is the only sane way to handle three hundred colors. Rendering happens inside a Shadow DOM so the theme’s CSS and ours cannot reach into each other. And the same app assigns a full media set per variant, so the gallery filters properly without depending on media order.

Rubik Variant Images swatch settings with custom swatch images and colors per variant

One honest caveat, because card swatches get promised too casually in this category. Product card swatches on collection pages are mapped separately from product page swatches, and that map covers 177+ themes against 386 on the product page. Our free theme compatibility checker tells you what is mapped for your theme, so check before you build a collection page plan around it. And if your colors are separate products rather than variants, card swatches will not join them at all: that is a different mechanism, covered in collection swatches for separate products.

“Hands Down the best customer support of all the variation/swatch apps I have used till date. The app does everything. From individual variant gallery to really detailed customizable swatch’s. All in a single app. Originally we used to use two different apps so this is so much more cost efficient for us. […] Bugs or not, the support will respond in less than a minute. […] The technical team will fix whatever issue you are having that SAME MOMENT. […] The app is top notch. you can customize it how ever you feel like, The options are really good. AI has been integrated, HELPS ALOT WITH SORTING IMAGES.”
Bellissima Covers, India, Rubik Variant Images on the Shopify App Store

You can see swatches and filtered galleries running on a real storefront in the live demo store, or read the getting started guide before touching your own theme.

FAQ

Which app should I use to fix blank swatches on the Showcase theme?

Try the free routes first, because a filename typo does not need an app. If you want the failure mode gone permanently, Rubik Variant Images, built by Craftshift, attaches the swatch image to each variant as a Shopify metafield instead of matching a filename, and Showcase is one of the 386 entries in its theme config. It holds 5.0 stars across 420 reviews and is free for one product, then $25 a month for 100. Where it is not the obvious pick: if your theme already reads Shopify’s option value swatches and you only need flat colors, the platform gives you that for nothing, and paying for an app you do not need is a bad trade.

Why does a missing swatch image not show an error?

Because a missing image is not an error condition in a browser. The request 404s, the browser moves on, and the page finishes rendering normally. The theme has no way to know the file was supposed to exist, so nothing is logged, nothing appears in the theme editor and nothing warns you in the admin. The only place it is visible is the network tab or the image URL itself.

What filename does the Showcase theme expect for a swatch?

Clean Canvas documents it as the handle of the variant color title: lowercase, spaces replaced with a dash, special characters removed, Latin alphabet only, saved as PNG. Their example is Fire Engine Red becoming fire-engine-red.png, and they specifically call out that waldgrün.png must be renamed waldgrun.png. From Showcase 10.0.0 onward the color list setting takes explicit pairs in the form Red:red.png instead, so check your theme version before renaming anything.

Where do the swatch image files go?

Clean Canvas now documents uploading them through the Shopify admin under Content, then Files. Older theme generations, and many other themes still, looked in the theme’s own Assets folder instead, which is why a lot of the advice online tells you to edit theme files. If you followed that older advice on a current Showcase build, the file is in a place the theme is not looking.

My option value has a slash in it, like Black/White. What do I do?

Under a filename-based system, avoid it. You cannot put a slash in a filename, so the derived name and the file you upload can never agree. The workarounds are to rename the option value to something like Black and White, or to move to a method that stores the swatch against the variant rather than matching it by name, at which point the characters in the value stop mattering entirely.

Can Showcase show a different set of photos per color without an app?

Partly. Clean Canvas documents a product page setting that only shows media associated with the selected variant, where the association comes from how you order the media in the admin rather than from assigning it. The documented limit is that it applies to a single variant option per product template, so a product where two options both change the photos is not covered.

Will a Showcase theme update break my swatches again?

Theme settings live inside the theme, so a swatch color list and a media grouping setting are worth rechecking after any update, and the 10.0.0 change to the color list format is a good example of why. App configuration set through Shopify’s theme app embed and block system is not stored in theme files, so a theme update leaves it alone.

Fix the one that is broken, then decide

Inspect the blank circle, read the URL, rename the file. That fixes today. Then look at how many colors you expect to add over the next year and ask whether you want to keep doing this by hand every time, because the answer to that question is the only reason to reach for an app at all.

Try Rubik Variant Images free →