Assign a unique set of images to each variant. When the customer selects that variant, the gallery filters to show only those images. The first image becomes the swatch thumbnail.

Single metafield: custom.variant_images on the variant.

Quick setup

  • Create metafield: custom.variant_images on Variants, type List of files (Image).
  • Upload images: Content > Files.
  • Assign per variant: open a variant → Metafields → Variant images → add images. First image = swatch thumbnail.

Where it works

  • Product page (PDP) main gallery.
  • Featured product section.
  • Variant quick-view modal.
  • Product card swatch thumbnails (tabbed display).

When the metafield is empty, all product images show as fallback. Set images only on variants where you want filtering.

Step 1: Create the metafield definition

One-time setup per store.

  1. Admin → Settings > Custom data > Variants.
  2. Click Add definition.
  3. Name: Variant images
  4. Namespace and key: custom.variant_images
  5. Type: File → check List of files → accepted file types: Images.
  6. Save.

Step 2: Upload images

  1. Admin → Content > Files.
  2. Upload the images you plan to use.

Tip: name files clearly (e.g. red-tshirt-front.jpg) for easier selection later.

Step 3: Assign images to a variant

  1. Open the product in Admin.
  2. Scroll to Variants, click a variant.
  3. Scroll to Metafields on the variant page.
  4. Click Variant images, select images.
  5. Order matters: first image = swatch thumbnail and gallery start.
  6. Save.

Repeat per variant where you want a filtered gallery.

How it behaves

Variant state Gallery
Has variant images set Filters to those images, in your order
No images set Shows all product images (fallback)
Variant change Gallery instantly filters to new variant
Color option First image = swatch thumbnail

Things to know

  • Variant-level metafield, not product-level. Setting it on the product itself does nothing.
  • Images don't need to be added to the product's main media library. The metafield links them directly.
  • The variant quick-view modal renders via the same product section. No separate setup.
  • For many variants at once, use Shopify's bulk metafield editor or CSV import.