> For the complete documentation index, see [llms.txt](https://modutheme.gitbook.io/helix/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://modutheme.gitbook.io/helix/how-to-guides/how-to-set-up-multiple-variant-images.md).

# 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:

{% tabs %}
{% tab title="Product page" %}
![Product page gallery switching to the selected variant's media](https://3215967854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlyCMfKbEVTf3hu8uxjSZ%2Fuploads%2Fgit-blob-320915d712b45120cef0986f522e3e0d9ec8d16f%2Fhow-to-variant-images-product-page.png?alt=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.
{% endtab %}

{% tab title="Product card" %}
![Product card primary and hover images changing with the variant](https://3215967854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlyCMfKbEVTf3hu8uxjSZ%2Fuploads%2Fgit-blob-672bbd0014d90be8c44fee41cdbbfb86e84b6d86%2Fhow-to-variant-images-product-card.png?alt=media)

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.
{% endtab %}
{% endtabs %}

{% embed url="<https://www.youtube.com/watch?v=dQ0466SjOL8>" %}
Video walkthrough: show only the selected variant's images with Helix.
{% endembed %}

***

## 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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
Variant media only works when **Only show media of the selected variant** is on (theme editor → [**Theme Settings → Variant pickers**](/helix/theme-settings/variant-pickers.md#variant-gallery)). 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.
{% endhint %}

***

## 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](https://3215967854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlyCMfKbEVTf3hu8uxjSZ%2Fuploads%2Fgit-blob-e432a70df7897e7b52caca7d197bdd0cc44522a7%2Fhow-to-variant-images-metafield.png?alt=media)

***

## 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](https://3215967854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlyCMfKbEVTf3hu8uxjSZ%2Fuploads%2Fgit-blob-9d051d79b72373a3d3d4240da3cec0c6016402ea%2Fhow-to-variant-images-add.png?alt=media)

{% hint style="info" %}
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.
{% endhint %}

***

{% hint style="info" icon="headset" %}
**Need help?**

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

<a href="https://go.crisp.chat/chat/embed/?website_id=6c25581e-794a-41b4-8552-52f3de1dd1f7" class="button secondary" data-icon="comments">Chat with us</a> <a href="https://modutheme.ticksy.com" class="button primary" data-icon="ticket">Submit a ticket</a>
{% endhint %}