Setting up Rubik Variant Images

Install and switch on

Install from the Shopify App Store. Shopify asks for the permissions the app needs, then drops you back in your admin with the app open.

Nothing appears on your storefront yet. The app draws its gallery and its swatches through a theme app extension, and that extension has to be enabled once per theme:

1. In your Shopify admin open Online Store, then Themes.
2. On the theme you are using press Customize.
3. Open App embeds in the left sidebar.
4. Find Rubik Variant Images and switch it on.
5. Press Save.

The app checks this for you. Its dashboard carries a Variant image status card that tells you whether the embed is on for the live theme, so if you are unsure, look there rather than hunting through the editor.

Publishing a new theme, or duplicating one, starts from a copy with the embed off. Enable it again on the new theme.

Configure your first product

Pick a product where the gallery is worst, usually one with several colours and a photo for each. Open it in the app and you will see its media on one side and its options on the other.

1. Choose the option that changes how the product looks. On most products that is colour, not size.
2. Drag each image onto the value it belongs to. A value can hold as many images as you like.
3. Put the image you want as the variant thumbnail first in its list.
4. Save, then open the product page on your storefront and select a value.

The gallery should now show that value's media and nothing else. If it shows everything, the section on troubleshooting below covers the three usual reasons.

A product you have not configured behaves exactly as it did before the app was installed, so there is no rush to do the whole catalogue.

Assigning at scale

Doing this by hand for a large catalogue is not the intent. There are two ways to do it in bulk, and they suit different shops.

Bulk assign, by gallery order

This reads the order your images already sit in inside Shopify. The first image of a variant opens a group, and every image after it belongs to that variant until the next boundary. If your gallery is already ordered colour by colour, this gets it right in one pass, costs nothing, makes no AI calls, and runs in the background over hundreds of products.

Automatic matching

The matcher reads five things about each image, the product title, the option name, the option value, the filename and the alt text, and it looks at the picture itself. It proposes an assignment you can correct before saving. It works on one product at a time and spends your plan's monthly AI allowance. Use it where the gallery order is a mess but the filenames or the photos are clear.

There is also an opt-in that sends a bulk run through the matcher instead of using gallery order, for a catalogue that is disorganised throughout.

Swatches on the product page

The same option values that filter the gallery can replace the theme's variant dropdown. Turn swatches on in the app and choose which option they apply to.

Three kinds are available and they mix across options, so colour can be image swatches while size stays as pill buttons:

• Image swatches, showing a crop of the variant's own photo or an image you upload.
• Colour swatches, a flat colour you pick.
• Pill buttons, for options with no visual, such as size or material.

Shape, size, spacing, borders, the selected state and the sold out treatment are all set in a visual editor, and there is a custom CSS field for anything it does not cover. The swatches render inside a shadow root, which means your theme's CSS cannot reach into them and break them, and theirs cannot leak out.

The swatch library

Setting the same colour on every product that sells Navy is work you should only do once. The swatch library holds one image or one colour per option value for the whole shop, so Navy set there applies everywhere that value appears.

Swatches on product cards

A shopper on a collection page sees one photo per product, usually whichever colour happens to be first. Card swatches put that product's values on its card, across collection pages, search results and home page listings.

Clicking a card swatch swaps the card image, and it can also update the card price and the add to cart link so the shopper lands on the variant they chose. Hovering previews the image.

This is off until you switch it on, in the app's swatch settings. It has its own style tab, separate from the product page, because a card is smaller and usually wants smaller swatches and a tighter row.

Card swatches are mapped theme by theme, and that list is shorter than the product page one. If yours is not covered, support can map it.

Settings worth knowing

Hide unassigned images

An image you never assigned shows for every variant. That is right for a size guide and wrong for a lifestyle shot of the red one. Turn this on and unassigned images disappear from the product page while still being available as the collection thumbnail.

The same image on several values

Off by default, because most shops want one photo to belong to one colour. Turn it on when a photo genuinely shows two values, a flat lay of the whole range for instance.

Overwriting variant featured images and media order

These decide whether saving a product also rewrites Shopify's own variant featured images and reorders the product media. Leave them on and the Shopify admin matches what shoppers see. Turn them off if something else in your stack owns that order.

The master switch

The Settings page has one switch that takes every storefront feature down without uninstalling anything. Assignments stay exactly where they are, ready for when you turn it back on. Give the product page a minute to catch up afterwards, because the storefront reads a metafield that Shopify caches briefly.

Themes and compatibility

The app ships integrations for more than 350 Shopify themes, among them the Dawn and Horizon families, Prestige, Impulse, Impact and Focal, and it reads Shopify's native variant selector as well as custom ones. Eight page builders are covered: EComposer, EcomWize, Foxify, GemPages, Instant, Omnise (formerly Beae), PageFly and Replo.

Because the app is a theme app extension, it never edits your theme files. Switching it off leaves the theme exactly as it was.

When you change theme

Enable the app embed on the new theme, then check a product page. The assignments live on the products, not in the theme, so nothing has to be redone.

When your theme is not on the list

Many unlisted themes work anyway, because the app also reads the native selector. If yours does not, send support the theme and they will map its selector and its gallery.

Other apps that touch the gallery

Another app that rewrites variant images or the variant picker can fight with this one. Tell support which app it is and they will work out a setup where the two coexist.

Troubleshooting

Nothing changed on the storefront

Check these three, in this order. They cover almost every case.

1. The app embed is enabled in the theme editor, on the theme that is actually live.
2. The product is configured in the app, not just opened in it.
3. The option you assigned images to is the one the theme's selector uses.

A change is not showing yet

The storefront reads a metafield that Shopify caches for a short time. Reload the product page after a minute, and check it with the theme editor closed, because a preview session can serve an older copy.

The variant's main image changed

That is the app setting the featured image to the first image of the value. Drag the one you want into first position, or turn off the overwrite option in the advanced settings.

Unassigned images are still showing

That is the default. Turn on hide unassigned images, described above.

Plans and limits

Plans differ in two things only: how many products you can configure, and how many images the automatic matcher may look at each month. Every feature is on every plan, including swatches and card swatches. The single exception is showing swatches on products you have not configured, which needs a paid plan.

Removing a configuration frees its slot again, so a plan's allowance can be moved around the catalogue.

Going over the limit does not break anything on the spot. The app warns you and gives you a 30 day window to upgrade or free some slots. Only after that window are the storefront features switched off, and they come back on their own as soon as the shop is inside its limit again.