Rebuy widgets can display your Shopify theme's color swatch images next to color variant options instead of the default solid color fill. Widget Variant Image Buttons — often called "Color Swatches" — keep your Rebuy widget swatches visually consistent with the swatches shown on your Shopify storefront, so shoppers see the same colors across product pages, Smart Cart, and Rebuy widgets.
This article walks through how Rebuy Color Swatches work, how to configure them, how to verify they're rendering, and how to troubleshoot the most common issues.
Screenshot example above of a Rebuy widget rendered on a storefront with a row of working color swatches (e.g., Retro, Futuristic Purple, Red) displayed as button-style image swatches under the product.
How Rebuy Color Swatches Work
Rebuy Color Swatches render by looking up an image in your Shopify theme's assets/ folder that matches each variant's color option value. When a Rebuy widget renders a product with color variants, it searches your Shopify theme's assets/ folder for a swatch image file whose name matches the variant's color option value. If a match is found, the swatch label uses that image as its background. If no match is found, the swatch falls back to a CSS background-color rendered from the variant value directly.
Color Swatches are a variant-level feature. Product-level swatches are not supported natively.
Before You Start: Widget Settings Requirements for Color Swatches
Before adding any color swatch images, the Rebuy widget itself must be configured to display variant selectors as button swatches. Without this setting, color swatches will not appear even if your theme assets are named correctly.
In the Rebuy dashboard:
Open the widget editor you want to show color swatches on.
Go to the Widget Settings tab.
Under General - View Options, select Display Selectors and Buttons.
Set Variant Selector Type to Buttons.
Click Save.
Screenshot example above of the Rebuy widget's Widget Settings → View Options → Display Selectors and Buttons panel, with Variant Selector Type set to Buttons.
Important: The widget editor will not pull in the variant "swatch" images. To confirm your Color Swatches are working, test using Rebuy's Preview Mode or view the widget directly on your live storefront.
Step-by-Step: Adding Color Swatch Images to Your Shopify Theme
Follow these steps in order to add Rebuy-compatible color swatch images to your Shopify theme.
Step 1 — Create a Swatch Image for Each Color Variant
Create one image file per color variant. Each image should visually represent that color — either a solid color tile or a textured swatch preview. Supported file types for Rebuy Color Swatches are .jpg, .jpeg, and .png. The formats .webp, .gif, and .svg are not supported and will be ignored.
Screenshot example above of product variant setup labeled with their corresponding filenames like color-retro.png, color-futuristic purple.png, etc.
Step 2 — Name Each Swatch File Using the Rebuy Naming Convention
Rebuy only matches swatch images that follow a specific filename pattern. Every swatch image filename must:
Begin with the prefix
color-or whatever product variant Option Label is used.Include the variant option value exactly as it appears in Shopify after the Option Label prefix
Use a
.jpg,.jpeg, or.pngextension
Format:
color-<variant-value>.<jpg|jpeg|png>
Examples:
Variant option value | Correct filename |
|
|
|
|
|
|
|
|
|
|
|
|
Step 3 — Upload the Swatch Images to Your Theme's assets/ Folder
Rebuy only scans your Shopify theme's assets/ folder. Files stored in snippets/, sections/, Content → Files, or anywhere else in the theme will not be picked up.
To upload:
In your Shopify admin, go to Online Store → Themes.
Click … → Edit code on the theme you want to update.
Open the Assets folder.
Click Add a new asset and upload each
color-*.png/.jpg/.jpegfile.Save the theme.
Screenshot examples above of the Shopify theme code editor, Assets folder expanded in the left sidebar, with several color-<value>.png files visible in the file list.
It may take a few minutes for Shopify to host the uploaded image at its CDN URL. See the Caching and Cache Clearing section below if new swatches are not appearing immediately.
Step 4 — Confirm the Variant Option Is Set Up in Shopify
In your Shopify product, make sure the variant option label is named Color (or Size for size swatches) and that each variant's option label and option values matches the swatch filename you uploaded in Step 2. The option name drives how Rebuy chooses whether to render buttons as color swatches.
Screenshot example above of a Shopify product's Variants section with an option named Color and several variant values (e.g., Retro, Futuristic Purple, Red) listed.
Rebuy Color Swatch Filename Naming Conventions
Rebuy uses two simple naming conventions when matching a swatch image filename to a variant option value.
Capitalization is ignored.
color-RED.png,color-Red.png, andcolor-red.pngall match a variant option value ofRed— any mix of uppercase or lowercase letters works.Everything else must match character-for-character. Spaces, hyphens, and underscores are not normalized or interchangeable — a space is not the same as a hyphen, and an underscore is not the same as either.
Worked Example 1 — Variant Option Value: Majestic Orange Sun
Filename | Matches? | Why |
| Yes* | Spaces line up with spaces |
| Yes* | Capitalization is ignored |
| No | Hyphens are not treated as spaces |
| No | Missing spaces |
Worked Example 2 — Variant Option Value: Red-moon-Glass
Filename | Matches? | Why |
| Yes | Hyphens and positions match; case ignored |
| Yes | Capitalization is ignored |
| Yes | Capitalization is ignored |
| No | Spaces are not treated as hyphens |
| No | Underscores are not treated as hyphens |
Common Mistakes When Setting Up Rebuy Color Swatches
These are the most frequent reasons Rebuy Color Swatches fail to render.
Wrong prefix.
swatch-red.pngorred.pngwill not be picked up. The prefix must be exactlycolor-.Wrong file extension. Only
.jpg,.jpeg, and.pngare scanned..webp,.svg, and.giffiles are ignored.Mismatched variant value. If the variant value is
Navy Bluebut the asset iscolor-navy.png, the swatch will not match. The portion aftercolor-must match the full variant value.Spaces vs. hyphens. If the variant value is
Navy Bluebut the asset iscolor-navy-blue.png, they will not match. Either rename the variant toNavy-Blue, or accept that swatches will not render (Shopify typically blocks uploading filenames with literal spaces).Extra
color-in the filename. If the filename containscolor-more than once (for example,color-my-color-red.png), only the portion after the lastcolor-is used for matching. In that example, Rebuy would try to match a variant namedred, notmy-color-red.File not in
assets/. Files stored insnippets/,sections/, Content → Files, or any other theme folder are not scanned by Rebuy.
Rebuy Color Swatch Fallback Behavior
If no matching theme asset is found for a given variant option value, the Rebuy swatch label falls back to rendering the variant value as a CSS background-color. This fallback works for standard CSS color names like red, blue, or hex values like #ff0000, but will appear blank or incorrect for non-color strings like Forest Green or Ocean Breeze. Supplying a matching theme asset is the reliable way to ensure swatches render correctly for branded or multi-word variant names.
How to Verify Rebuy Color Swatches Are Rendering
After uploading your swatch images, follow these steps to confirm Rebuy is picking them up.
Upload your
color-<value>.png(or.jpg/.jpeg) files to your theme'sassets/folder.Save the theme (it may take a few minutes for Shopify to host the image at its CDN URL).
Reload a storefront page where the Rebuy widget displays the relevant product.
Right-click the swatch label and choose Inspect (or open browser dev tools). You should see a
background-image: url(...)style pointing to the Shopify CDN URL of your asset.
Screenshot example above of Chrome browser dev tools Elements panel showing a .rebuy-color-label element with a background-image: url(...) pointing to a Shopify CDN color-<value>.png URL.
If the background-image is missing, resync product data, clear cache, double-check the filename, extension, variant option value, and that spaces/hyphens/underscores match exactly.
Caching and Cache Clearing for Rebuy Color Swatches
Rebuy caches Shopify theme asset responses for up to 24 hours. If you've just uploaded a new color-<value> asset and it isn't appearing in your widget yet, it's likely still being served from cache.
To force Rebuy to fetch the latest theme assets immediately:
In the Rebuy dashboard, open the Datasources Page > Cache Manager > Clear Cache
Find the Collections, Metafields, Presentment Prices Cache entry and click clear. Clearing this cache also clears Shopify's cached theme asset calls.
Return to the storefront and hard-refresh the page, or view the widget in an incognito session.
The swatch should now appear. You can optionally re-run the verification script from the previous section to confirm the asset file is picked up.
Screenshot example above of the Rebuy Cache Manager page with the Collections, Metafields, Presentment Prices Cache row highlighted and the clear button visible.
Rebuy Color Swatches Limitations
A few known limitations apply to Rebuy Color Swatches.
Variant-level only. Product-level swatches are not supported.
Not supported in Post-Purchase widgets.
Not supported in the Checkout Extensions Widgets.
Not supported in the Bundle Builder.
Frequently Asked Questions About Rebuy Color Swatches
Do Rebuy Color Swatches work with .webp or .svg files?
No, Rebuy Color Swatches do not work with .webp, .svg, or .gif files. Only .jpg, .jpeg, and .png files in the theme's assets/ folder are scanned for matching swatches. If your theme currently uses .webp or .svg color swatches elsewhere, you will need to re-export them as .jpg or .png to use them with Rebuy widgets.
Why did my new Rebuy Color Swatch not appear after I uploaded it?
A newly uploaded Rebuy Color Swatch often does not appear immediately because Rebuy caches Shopify theme asset responses for up to 24 hours. To see the new swatch right away, clear the Collections, Metafields, Presentment Prices Cache in the Rebuy Cache Manager and hard-refresh the storefront page.
Does the swatch filename matching for Rebuy Color Swatches care about capitalization?
No, capitalization does not matter in Rebuy Color Swatch filenames. color-RED.png, color-Red.png, and color-red.png all match a variant value of Red. However, spaces, hyphens, and underscores are not interchangeable and must match the variant value exactly.
Can I use Rebuy Color Swatches in Post-Purchase, Checkout, or Bundle Builder widgets?
No, Rebuy Color Swatches are not supported in Post-Purchase widgets, the Checkout Widget, the Bundle Builder, or Recharge thank-you/checkout widgets. This is due to Shopify extension limitations in those surfaces. For swatch-like behavior in these widgets, a custom solution is required — merchants can book time with Rebuy's Partner team at https://rebuy.partnerpage.io/matchmaking.
Are product-level swatches supported by Rebuy?
No, product-level swatches are not supported natively by Rebuy. Rebuy Color Swatches are a variant-level feature only. Merchants who need product-level swatches will need a custom widget template that references tags, metafields, or metaobjects, which is outside the scope of standard Rebuy support.
What happens if Rebuy can't find a matching swatch image?
If Rebuy cannot find a matching swatch image in the theme's assets/ folder, the swatch label falls back to rendering the variant value as a CSS background-color. This works for standard color names like red or blue and hex values like #ff0000, but will appear blank or incorrect for non-color strings like Forest Green or Ocean Breeze. Uploading a matching theme asset is the reliable way to ensure swatches render correctly.