How to set up variant media

By default, Helix shows only the featured image for the selected variant. The variant gallery metafield lets you give each variant option value its own full set of media — images and videos — which changes two places:

Product page

Product page gallery switching to the selected variant's media

Selecting a variant (for example, "Red") swaps the whole gallery to that variant's media, so shoppers see every red image and video instead of just the featured image.

Product card

Product card primary and hover images changing with the variant

Selecting a variant swaps the card's primary image to that variant's image, and its secondary (hover) media to the first item in that variant's gallery, replacing the card's usual second image.

Video walkthrough: show only the selected variant's images with Helix.

---

How it works

Helix reads the custom.variant_gallery metafield on a variant. When a customer selects a variant, the gallery shows the variant's own image first, then the media stored in that metafield.

The gallery groups by the first option (e.g. Color). For each value of that option, Helix reads the metafield from the first variant with that value — so every size of "Red" shows the media saved on the first "Red" variant.

Variant media only works when Only show media of the selected variant is on (theme editor → Theme Settings → Variant pickers). With it off, Helix ignores the metafield and the product page shows all of the product's media. The setting is on in the Helix, Marlow and Selene styles.

---

Step 1 — Create the metafield definition

1. In Shopify admin, go to Settings → Metafields and metaobjects → Variants.

2. Click Add definition and set:

   • Name — Variant gallery

   • Namespace and key — custom.variant_gallery

   • Type — File, list of files, with Accepted file types set to Media files only (images and videos)

3. Click Save.

Creating variant gallery metafield definition

---

Step 2 — Add media to each variant

1. In Shopify admin, go to Products and open a product.

2. In the Variants section, open the first variant of an option value (for example, the first size of "Red").

3. Scroll to Metafields → Variant gallery.

4. Add the images and videos that should appear when this option value is selected. Skip the variant's own image — Helix always shows it first.

5. Click Save.

Repeat for the first variant of every other option value.

Adding media to the variant gallery metafield

Set the metafield on the first variant of each option value only. If you have "Red / Small" and "Red / Large", add media to "Red / Small" (the first one) — Helix uses it for every variant that shares the same first option, and ignores the metafield on the others.

---

Need help?

Whether you have a question, run into an issue, or just need some guidance, our support team is here to help.

Chat with us Submit a ticket