How to store multiple images per variant with Shopify metafields

If you have searched for a shopify variant image metafield setup, you already know the problem: Shopify only lets you attach one image per variant natively, and you want each color, style, or finish to carry a whole set of its own photos. A metafield is the native way to store that extra data. It’s a custom field bolted onto each variant that can hold a list of image file references, so the red shirt can point at five red photos and the blue one at five blue photos. No duplicate products. No messy workarounds.

But storing the images is only half the work. Once the data sits in a metafield, something in your theme has to read it and swap the gallery when a shopper picks a swatch. That’s where most guides go quiet. This one won’t.

We build a Shopify app that does exactly this for a living, so we’ve seen every version of the manual metafield route: the ones that work, the ones that break on the next theme update, and the ones that quietly stop rendering after a shopper on mobile taps a variant. Below is the honest version. How to do it by hand with metafields, what to reference in your theme, where it bites you, and the no-code path if you’d rather skip the Liquid entirely.

In this post

• Why one image per variant is not enough
• What a variant image metafield is
• Create the metafield definition
• Assign images to each variant’s metafield
• Reference the metafield in your theme
• The catch with the manual metafield route
• The no-code way: Rubik stores it in metafields for you
• FAQ
• Related reading

Why one image per variant is not enough

Shopify gives every variant a single “featured image” slot. One photo. That’s the whole native feature. Fine for a mug that only differs by the print on one side. Useless for apparel, furniture, jewelry, or anything a shopper wants to inspect from several angles.

Picture a store that sells one hoodie in six colors. Each color deserves a front shot, a back shot, a fabric close-up, and a lifestyle photo. That’s four images per color, twenty-four total, and Shopify’s native setup will only pin one of them to each variant. The rest sit in a shared gallery where the wrong color shows up next to the right swatch. Shoppers get confused. Returns go up. Nobody wins.

So the goal is two things at once: store multiple images per variant, then show only selected variant images when someone clicks a swatch. Metafields cover the first part. The theme covers the second. Let’s build both.

What a variant image metafield is

A Shopify variant image metafield is a custom field attached to a single variant that you set to hold a list of image file references, so each variant can carry its own set of photos instead of just one. Think of it as a labeled drawer on every variant. You decide what goes in the drawer, and the type you choose decides what shape the data takes.

For multiple images per variant, the type that matters is list.file_reference, which Shopify’s admin labels as “File” set to “List of values.” A single file reference holds one image. A list holds many, in the order you arrange them. That ordering matters later, because it becomes the sequence your variant image gallery shows.

Why file references and not URLs? Because file references point at assets already living in your Shopify Files library, so they get served from Shopify’s CDN and stay tied to your store. No broken links if you rename something. And because the data loads with the page itself, there’s no external call slowing the gallery down. Metafields are quietly one of the best features Shopify shipped, and most merchants never touch them. That’s a shame.

Create the metafield definition

Before you can assign anything, Shopify needs a definition. This is the template that tells every variant “you have a field called variant images, and it holds a list of files.” You create it once, and it applies across your whole catalog.

1. In your Shopify admin, go to Settings, then Custom data.
2. Choose Variants from the list of things you can attach metafields to.
3. Click Add definition.
4. Name it something clear like “Variant images.” Shopify auto-fills a namespace and key (for example, custom.variant_images). Write that key down; you’ll need it in the theme.
5. For the type, pick File, then set it to List of values. Under the hood that’s the list.file_reference type. You can restrict it to images only.
6. Save.

That’s the definition done. Every variant in your store now has an empty variant image metafield waiting to be filled. Nothing shows on the storefront yet, because you haven’t assigned images and your theme doesn’t know the field exists. Two more steps.

Assign images to each variant’s metafield

Now the tedious part. Open a product, click into an individual variant, and scroll to the Metafields section on the variant page. You’ll see your “Variant images” field. Click it, then add files from your library (or upload new ones) and arrange them in the order you want the gallery to show. Repeat for every variant.

For that six-color hoodie, that’s six trips through the same screen. For a catalog with hundreds of products and a dozen variants each? You do the math. This is the moment most people realize why apps exist. Shopify caps you at 250 media per product and up to 2,048 variants per product when you use Combined Listings, so the ceiling is high, but the manual labor to fill it by hand is brutal.

Want to sanity-check your setup as you go? Our free variant image checker scans a product and flags variants that are missing images, and the variant image calculator tells you how many total images your combination of options will need before you start uploading. Better to know the number up front.

Reference the metafield in your theme

Here’s the step the quick tutorials skip. Assigning images to a metafield does nothing on its own. The data just sits there. Your theme has to read the selected variant’s metafield list and render it inside the product media gallery, and that means editing Liquid.

In most themes you’d open the product media section (in Dawn-based themes that’s around main-product.liquid or a media snippet) and loop the variant’s metafield. Roughly:

{%- assign variant_media = variant.metafields.custom.variant_images.value -%}
{%- for media in variant_media -%}
  {{ media | image_url: width: 1200 | image_tag }}
{%- endfor -%}

Then you need JavaScript that listens for the variant change event and swaps which set of images is visible, plus logic to hide every other variant’s photos so only the selected variant’s media shows. And you have to make sure it plays nicely with the theme’s existing gallery, its thumbnails, its zoom, and its mobile swipe behavior. Do you love debugging theme JavaScript at midnight? Most merchants don’t.

When we tested our own rendering across 350+ themes, the gallery structure was different in almost every one. Sticky headers, lazy-loaded images, custom variant selectors that don’t fire the standard event: a hand-rolled loop that works on Dawn can fall apart on Impulse or Prestige. That’s not a knock on you. It’s just how theme code goes.

The catch with the manual metafield route

The metafield approach is legitimate. It’s native, it’s fast, and the data belongs to you. But be honest about what you’re signing up for. Three things bite people, and they bite hard.

The problem	Why it hurts
It needs code	Reading the metafield and swapping the gallery both require Liquid and JavaScript edits. Not beginner territory, and a small mistake can break the whole product page.
It breaks on theme updates	Your edits live in theme files. Update the theme or switch to a new one and your custom gallery code is gone. Back to square one.
It’s tedious at scale	Assigning images variant by variant across a real catalog eats hours. There’s no built-in bulk workflow for it.

That third one is the quiet killer. A store with 40 products might grit its teeth through it. A store with 800 won’t. And the theme-update problem means even a working setup has a shelf life. Is that a dealbreaker? Not always. If you’re comfortable in Liquid and your theme is stable, the manual route is fine. For everyone else, there’s a shortcut that keeps the metafield benefit and drops the code.

The no-code way: Rubik stores it in metafields for you

This is the part where we tell you what we built and why. Rubik Variant Images & Swatch writes the variant-to-image grouping into metafields for you and renders the filtered gallery on the product page, with no Liquid editing on your side. Same native storage. None of the theme surgery. Because the grouping lives in metafields, it survives theme switches and theme updates, which is the exact fragility the manual route can’t escape.

You get three ways to assign, depending on how big your catalog is:

• Manual drag-and-drop. Grab an image, drop it on a variant. Fast for a handful of products, and the most precise when you want full control.
• AI auto-assign. Per product, one product at a time. It reads that product’s data (product and variant names, image filenames, and image alt text) to match each photo to the right variant. Runs on monthly AI credits. Handy when your filenames and alt text already describe the colors. Our AI auto-assign walkthrough shows it in action.
• Bulk assign. Image-order based grouping. It reads the Shopify gallery order and the featured-image boundaries to split photos into variant groups, running in the background across hundreds of products at once. No AI. This is the one that saves the 800-product store.

On the storefront, RVI filters the gallery so only the selected variant’s media shows, renders swatches on the product page (image swatches, color swatches, or pill and button styles), and can even show product-card swatches on collection and search pages for a single product’s own variants. It supports images, videos, and 3D models per variant. It loads with the page (metafield-based loading, no external API calls), uses Shadow DOM so its CSS stays isolated from your theme, and works with the native variant selector or a custom one. Compatible with 350+ themes including Dawn, Horizon, Craft, Sense, Refresh, Impulse, Impact, Prestige, and Focal, plus seven page builders: Beae, EComposer, Foxify, GemPages, Instant, PageFly, and Replo.

One boundary worth stating plainly, because we get asked constantly. RVI works on the product page (and product cards for one product’s own variants). It does not link separate products together, and it does not build collection swatches across different products. If that’s what you’re after, that’s a different job handled by Rubik Combined Listings, which can group separate products as variants. Keep the two in their lanes and you’ll never fight the tool.

Pricing is flat, not tied to your Shopify plan: Free at $0/month for 1 product, Starter $25/month for 100 products, Advanced $50/month for 1,000 products, and Premium $75/month for unlimited. Every tier includes monthly AI credits. If you want a deeper walkthrough of the whole setup, the complete variant images guide covers it end to end, and if images aren’t rendering, the not showing fix is the first place to look. Want an outside take? The Shopify variant image apps compared roundup lines up the options.

“Rubik Variant Images helped me organize my product images without needing to duplicate them for each variant, which is great for page speed. I had some questions about assigning images when using multiple options like size and color, and the support team (especially Farid) was very responsive and helpful. […] If you have products with multiple variants and want full control over which images show for each one, without hurting your page load speed, this app is a great solution. It’s lightweight, easy to use once you understand the logic, and the support is excellent.”

Pack Ship Mail Supplies, US, 2025-07-18. Rubik Variant Images on the Shopify App Store

Before you commit either way, it’s worth running the free theme checker to confirm your theme’s gallery structure, and reading up on variant images with multiple options if you sell by size and color together (that combination trips up more setups than any other).

See the live demo store, watch the tutorial video, or read the getting started guide.

FAQ

Can Shopify variants have multiple images natively?

Not directly. Shopify’s built-in feature assigns one featured image per variant. To store multiple images per variant you either use a variant metafield of type list.file_reference and edit your theme to read it, or install an app that handles the storage and rendering for you.

What metafield type stores multiple images per variant?

Use list.file_reference, shown in the admin as the File type set to List of values. A single file reference holds one image, while the list version holds several in the order you arrange them. Create it under Settings, Custom data, Variants, Add definition.

Do I need code to display variant image metafields?

With the manual metafield route, yes. Your theme has to loop the variant’s metafield list in Liquid and swap the gallery with JavaScript when the shopper changes variant. Rubik Variant Images does the rendering for you, so no theme code edits are needed on your side.

Will a variant image metafield survive a theme change?

The metafield data survives, because it lives on the variant, not in theme files. But the Liquid and JavaScript you added to display it live inside the theme, so those edits disappear on a theme switch. An app that stores the grouping in metafields and renders it keeps working across theme changes.

Does Rubik Variant Images use metafields?

Yes. RVI writes the variant-to-image grouping into metafields, so the data loads with the page and makes no external API calls. That’s why the gallery filters fast and stays intact when you update or switch your theme. You never touch Liquid to make it work.

Can metafields link separate products together?

Variant image metafields work within a single product, so they cannot link separate products or build collection swatches across different products. That job belongs to Rubik Combined Listings, which groups separate products and shows swatches across them on collection pages.

Related reading

• Why Shopify shows only one image per variant, and how to fix it
• How to show only the selected variant’s images
• How many images can you add per variant on Shopify?
• Craftshift: multiple images per variant, explained
• Rubikify: separate products vs variants for SEO