Variant Image Tagging Guide

Overview

When the "Hide unselected variant media" setting is enabled in the Product Media Gallery block, you can now associate multiple images with each variant using a simple alt text tagging system.

How It Works

The gallery will hide images based on two criteria:

1. Original Shopify behavior: Hides images that are directly attached to other variants (the single image per variant)
2. Enhanced behavior: Hides images tagged for other variants in their alt text

Both behaviors can optionally be limited to products with specific product tags. This is useful when one product template is shared by normal products and specialized flows like Hat Lab.

How to Tag Images

Add a tag to the alt text of each image using this format:

variant-{option1}-{option2}-{option3}

Examples

Product with Color and Size variants:

For a "Red" and "Small" variant:

• Alt text: Red t-shirt front view variant-red-small
• Alt text: Red t-shirt back view variant-red-small
• Alt text: Red t-shirt detail variant-red-small

For a "Blue" and "Large" variant:

• Alt text: Blue t-shirt front view variant-blue-large
• Alt text: Blue t-shirt back view variant-blue-large

Product with single option (Color only):

For a "Red" variant:

• Alt text: Product image variant-red

Important Rules

1. Use lowercase and hyphens: Variant tags are automatically converted to lowercase with hyphens (using Liquid's handleize filter)

   • "Red Small" becomes variant-red-small
   • "Dark Blue" becomes variant-dark-blue
   • "XL" becomes variant-xl

2. Order matters: Options must be in the same order as defined in Shopify:

   • If your options are "Color" then "Size", use variant-red-small (not variant-small-red)

3. Tag placement: The variant- tag can appear anywhere in the alt text

   • ✅ Product name variant-red-small lifestyle shot
   • ✅ variant-red-small - Product detail view
   • ✅ Beautiful red shirt variant-red-small on model

4. Untagged images: Images without a variant- tag in their alt text will show for ALL variants

Setting Up in Shopify Admin

1. Go to Products > Select your product
2. Scroll to Media section
3. For each image, click the image options and select Edit
4. In the Alt text field, add your variant tag
5. Click Done

Example Setup for a T-Shirt

Let's say you have a t-shirt with these variants:

• Red / Small
• Red / Large
• Blue / Small
• Blue / Large

And 8 images total (4 images per color):

Red variant images:

Alt text: "Red t-shirt front view variant-red-small"
Alt text: "Red t-shirt back view variant-red-small"
Alt text: "Red t-shirt on model variant-red-small"
Alt text: "Red t-shirt detail close-up variant-red-small"

Blue variant images:

Alt text: "Blue t-shirt front view variant-blue-small"
Alt text: "Blue t-shirt back view variant-blue-small"
Alt text: "Blue t-shirt on model variant-blue-small"
Alt text: "Blue t-shirt detail close-up variant-blue-small"

Result: When a customer selects "Red / Small", they'll only see the 4 red images. When they select "Blue / Small", they'll only see the 4 blue images.

Sharing Images Across Similar Variants

If you want the same images to show for multiple similar variants (e.g., all sizes of the same color), you have two options:

Option 1: Tag with multiple variant combinations

Add multiple variant tags to the alt text:

Alt text: "Red t-shirt detail variant-red-small variant-red-medium variant-red-large"

Option 2: Don't include the option in the tag

If you only want to filter by color (not size), use tags without the size:

Alt text: "Red t-shirt detail variant-red"

⚠️ Warning: This approach requires custom code modifications to the theme and is not currently supported out of the box.

Enabling the Feature

1. Go to Theme Customizer
2. Navigate to your product template
3. Select the Product Media Gallery block
4. Enable "Hide unselected variant media"
5. (Optional) Add one or more product tags to "Only hide variant images for product tags" if the setting should only affect tagged products
6. (Optional) Enable "Hide untagged images (strict mode)" if you want ONLY tagged images to show
7. (Optional) Add one or more product tags to "Only strict-hide variant images for product tags" if strict mode should only affect a narrower group
8. Save your changes

Setting Options

Hide unselected variant media (Required)

• Enables the variant filtering feature
• Hides images attached to other variants
• Hides images tagged for other variants

Only hide variant images for product tags (Optional)

• Accepts one product tag or comma-separated product tags
• When blank: variant image hiding applies to all products, matching the previous behavior
• When filled in: variant image hiding only applies when the current product has one of those exact tags

Hide untagged images (strict mode) (Optional)

• Only appears when "Hide unselected variant media" is enabled
• When OFF: Untagged images show for all variants (default)
• When ON: Only images with matching variant tags show (strict mode)

Only strict-hide variant images for product tags (Optional)

• Accepts one product tag or comma-separated product tags
• When blank: strict mode follows the regular hide variant image scope
• When filled in: strict mode only applies when the current product also has one of those exact tags

Hat Lab Example

If normal products and Hat Lab products share the same product template:

1. Tag Hat Lab products with hat-lab
2. Enable "Hide unselected variant media"
3. Enter hat-lab in "Only hide variant images for product tags"
4. Leave normal products untagged

Products tagged hat-lab will hide non-matching variant media. Normal products on the same template will keep their extra media because they do not match the product tag scope.

For multiple Hat Lab-style flows, enter comma-separated tags:

hat-lab, custom-hats

Troubleshooting

Images aren't hiding:

• Check that "Hide unselected variant media" is enabled
• If "Only hide variant images for product tags" is filled in, confirm the product has one of those exact tags
• Verify alt text tags match the exact variant option names (lowercase with hyphens)
• Confirm option order matches Shopify's option order

Some images show for wrong variants:

• Make sure there are no typos in variant tags
• Check that option names are handleized correctly (spaces → hyphens, lowercase)

Images disappear completely:

• Ensure at least one image is tagged for each variant
• Check that untagged "general" images exist if needed
• If strict mode is scoped by product tag, confirm only the intended products have that strict-mode tag

Technical Details

The system uses Liquid's handleize filter to convert variant option values:

• Converts to lowercase
• Replaces spaces with hyphens
• Removes special characters

Example transformations:

• "Dark Blue" → dark-blue
• "Extra Large" → extra-large
• "Red/Orange" → red-orange

Best Practices

1. Always include descriptive alt text for accessibility, with the variant tag as a suffix
2. Use consistent naming across all products
3. Tag all variant-specific images to avoid confusion
4. Keep some untagged images for general product information that applies to all variants
5. Test thoroughly after setting up to ensure correct images show for each variant