> 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 multiple variant images
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 images, which changes two places:
{% tabs %}
{% tab title="Product page" %}
Selecting a variant (for example, "Red") swaps the whole gallery to that variant's images, so shoppers see every red photo instead of just the featured one.
{% endtab %}
{% tab title="Product card" %}
Selecting a variant swaps the card's **primary** image to that variant's image, and its **secondary** (hover) image to the first image from that variant's gallery, replacing the card's usual second image.
{% endtab %}
{% endtabs %}
***
## How it works
Helix reads the `custom.variant_gallery` metafield on a variant. When a customer selects a variant, the gallery shows the images stored in that metafield.
{% hint style="info" %}
The gallery groups by the **first option** (e.g. Color). All variants that share the same option value use the same gallery.
{% 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 — Image and video, list of values
3. Click **Save**.
***
## Step 2 — Add images to each variant
1. In Shopify admin, go to **Products** and open a product.
2. In the **Variants** section, click a variant.
3. Scroll to **Metafields → Variant gallery**.
4. Upload the images that should appear when this variant is selected.
5. Click **Save**.
{% hint style="info" %}
Set the metafield on only one variant per option value. If you have "Red / Small" and "Red / Large", add images to one of them — Helix uses the same gallery for every variant that shares the same first option.
{% endhint %}
{% hint style="info" %}
The gallery filtering is controlled by one setting: **Only show media of the selected variant** (in the theme editor, under [**Theme Settings → Variant pickers**](/helix/theme-settings/variant-pickers.md#variant-gallery)). Turn it **on** to show only the selected variant's images; leave it **off** and the product page shows all of the product's media. It's off by default.
{% 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.
Chat with us Submit a ticket
{% endhint %}