Set up multiple images per variant

By default, Shopline lets you assign one featured image to each product variant. But what if your product needs multiple images per variant — for example, a chair available in Purple and Olive, where each color needs a front view, a side view, and a close-up?

The Multiple media per variant feature solves this. Using a variant-level metafield called gang_media, you can group multiple product images together and associate them with a specific variant. When a customer selects that variant, the product gallery automatically filters to show only the images in that group — hiding everything else.

As shown below, the Cocoon Arm Chair has two color variants — Purple and Olive. Each variant displays its own set of 4 images. Selecting Purple shows only purple chair photos; switching to Olive swaps the entire gallery to olive chair photos.

On this page

1. How it works
2. Set up the metafield definition
3. Assign images to each variant
4. Enable the feature in Theme Editor
5. How the gallery filtering works
6. Verify your setup
7. Troubleshooting

1. How it works

The feature relies on three layers working together:

1. Metafield theme.gang_media — A list-type metafield attached to each variant. It contains references to the specific media (images, videos) that should display when that variant is selected.
2. Theme Editor settings — Two toggles in the Product Media block control the behavior: Hide unselected variant media and Multiple media per variant.
3. Gallery filtering — When a customer clicks a variant, the theme checks the metafield and shows only the matched media in the gallery (both the main carousel and thumbnails).

2. Set up the metafield definition

Before assigning images to variants, you need to create the metafield definition in your Shopline admin.

Steps

1. From your Shopline admin, go to Settings > Custom data (or Metafields).

   

2. Select Product variants as the metafield owner.

   

3. Click Add fields and configure the definition to match the following:

   • Field Name: Gang media (or any descriptive name)
   • Namespace: theme
   • Key: gang_media
   • Data Type: Document
   • Assignment Type: Multiple values

   

4. Save the definition.

3. Assign images to each variant

Now that the metafield definition exists, you can assign images to individual variants.

Steps

1. From your Shopline admin, go to Products and open a product.
2. Scroll down to the Variants section.
3. Click on a variant to open its detail page.
4. Find the Gang media metafield (under the Metafields section).
5. Click to add files — select the product images that should display when this variant is selected.
6. Repeat for each variant.

Here's how it looks on the Cocoon Arm Chair product — the Purple variant has its gang_media metafield populated with multiple images:

Example

Using the Cocoon Arm Chair as an example — it has two color variants, each with multiple media files assigned:

Purple variant → gang_media: [
  Cocoon Arm Chair-purple-01.webp,
  Cocoon Arm Chair-purple-02.webp,
  Cocoon Arm Chair-purple-03.webp,
  Cocoon Arm Chair-purple-04.webp,
  Cocoon Arm Chair-purple-05.webp,
  Cocoon Arm Chair-purple-06.webp,
  Cocoon Arm Chair-purple-07.webp,
  Cocoon Arm Chair-purple-video.mp4
]

Olive variant → gang_media: [
  cocoon-arm-chair-olive-01.webp,
  cocoon-arm-chair-olive-02.webp,
  cocoon-arm-chair-olive-03.webp,
  cocoon-arm-chair-olive-04.webp,
  cocoon-arm-chair-olive-05.webp,
  cocoon-arm-chair-olive-06.webp,
  cocoon-arm-chair-olive-07.webp,
  cocoon-arm-chair-olive-08.webp,
  cocoon-arm-chair-olive-video.mp4
]

When a customer selects Purple, the gallery shows only the 8 purple media files (7 images + 1 video). Switching to Olive swaps the entire gallery to the 9 olive media files (8 images + 1 video).

4. Enable the feature in Theme Editor

With the metafield data in place, enable the feature in the Theme Editor.

Steps

1. From your Shopline admin, go to Online Store > Design.
2. Under Current Theme, click Design (or Customize) to open the Theme Editor.
3. Navigate to a Product page template.
4. Click on the Product media block in the block list.
5. Enable the following settings:

Hide unselected variant media (enabled by default)

This toggle must be on for the next setting to appear. When enabled, the gallery hides images associated with other variants and only shows images for the currently selected variant.

Multiple media per variant (disabled by default)

This toggle only appears when "Hide unselected variant media" is on. Turn it on to activate the gang_media metafield filtering. The setting description includes a link to the setup guide.

5. How the gallery filtering works

Understanding the filtering logic helps you troubleshoot issues:

1. Customer selects a variant (e.g., "Navy").
2. The theme retrieves the variant's metafields from the theme namespace.
3. It checks if gang_media exists and contains a list of media references.
4. If found: hide all product media by default, then loop through the gang_media list and show only matching media.
5. If not found: fall back to the standard behavior (show the variant's single featured image, hide other variant images).
6. Both the main gallery carousel and the thumbnail strip are filtered simultaneously.
7. On the JavaScript side, when a variant changes, the gallery resets and re-applies the filtering.

Behavior without gang_media

If "Hide unselected variant media" is on but "Multiple media per variant" is off (or the variant has no gang_media metafield), the theme falls back to the standard behavior: it shows the variant's featured image and hides images that are associated with other variants.

Behavior with gang_media

When "Multiple media per variant" is on and the variant has a gang_media metafield, the theme completely replaces the gallery contents with only the media listed in the metafield. Any product media not in the list is hidden.

6. Verify your setup

After configuring everything, preview a product in the Theme Editor and click through different variants. Use this checklist:

• Metafield definition exists: Variants > theme.gang_media (type: list of files).
• Each variant has images assigned in the gang_media metafield.
• All referenced images are uploaded as product media on the product.
• Hide unselected variant media is enabled in the Product media block.
• Multiple media per variant is enabled in the Product media block.
• Clicking a variant shows only the images assigned to it.
• Thumbnails update to match the filtered gallery.
• Switching between variants correctly swaps the image sets.

7. Troubleshooting

Swatches/variants work but gallery doesn't filter

Check that both toggles are enabled in the Product media block settings. "Multiple media per variant" only appears when "Hide unselected variant media" is on.

Gallery shows all images regardless of variant

The metafield namespace/key might be incorrect. It must be exactly theme.gang_media. Also verify the metafield type is set to "list" (not a single file reference).

Some images are missing from the gallery

Make sure the images referenced in gang_media are uploaded as product media on the product itself, not just in the Shopline Files library. The metafield references product media IDs, not file URLs.

Feature works on some product pages but not others

Check that the Product media block on the specific template has both toggles enabled. Different product templates (e.g., product.chairs vs product.sofas) have separate settings.

---

Need Further Assistance

If you encounter any issues or need additional help with your Maison theme, please reach out to our support team via our website for assistance.