Visual Guide: Variant Image Tagging
How It Works - Visual Flow
┌─────────────────────────────────────────────────────────────┐
│ PRODUCT: T-Shirt with 8 Images │
│ OPTIONS: Color (Red, Blue) + Size (S, M, L) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ALL IMAGES IN SHOPIFY: │
│ │
│ 1. "Red front variant-red-s" │
│ 2. "Red back variant-red-s" │
│ 3. "Red detail variant-red-s" │
│ 4. "Red model variant-red-s" │
│ 5. "Blue front variant-blue-s" │
│ 6. "Blue back variant-blue-s" │
│ 7. "Blue detail variant-blue-s" │
│ 8. "Blue model variant-blue-s" │
│ 9. "Size chart" (no tag) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┴──────────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Customer Selects: │ │ Customer Selects: │
│ Red / Small │ │ Blue / Large │
└─────────────────────┘ └─────────────────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ SHOWS THESE IMAGES: │ │ SHOWS THESE IMAGES: │
│ │ │ │
│ 1. Red front ✓ │ │ 5. Blue front ✓ │
│ 2. Red back ✓ │ │ 6. Blue back ✓ │
│ 3. Red detail ✓ │ │ 7. Blue detail ✓ │
│ 4. Red model ✓ │ │ 8. Blue model ✓ │
│ 9. Size chart ✓ │ │ 9. Size chart ✓ │
│ │ │ │
│ (5 images total) │ │ (5 images total) │
└─────────────────────┘ └─────────────────────┘
Before vs After Implementation
BEFORE (Original Shopify Behavior)
Customer selects: Red / Small
Gallery shows:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Red front │ │ Red back │ │ Red detail │ │ Red model │
│ (attached) │ │ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Blue front │ │ Blue back │ │ Blue detail │ │ Blue model │ ❌ Problem!
│ (unattached)│ │ (unattached)│ │ (unattached)│ │ (unattached)│ Shows blue images
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ when red selected
Only 1 image per variant could be hidden!
AFTER (With Alt Text Tagging)
Customer selects: Red / Small
Gallery shows:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Red front │ │ Red back │ │ Red detail │ │ Red model │
│ variant- │ │ variant- │ │ variant- │ │ variant- │
│ red-s │ │ red-s │ │ red-s │ │ red-s │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
Blue images are hidden! ✅
All images tagged with variant-red-s show!
Alt Text Tagging Format
┌────────────────────────────────────────────────┐
│ DESCRIPTIVE TEXT + variant-{identifier} │
│ │
│ Examples: │
│ ✓ "Red t-shirt front view variant-red-small" │
│ ✓ "variant-red-small Red shirt" │
│ ✓ "Shirt in red variant-red-small on model" │
└────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ VARIANT IDENTIFIER FORMAT: │
│ │
│ variant-{option1}-{option2}-{option3} │
│ │
│ Where each option is "handleized": │
│ - Lowercase │
│ - Spaces → hyphens │
│ - Special chars removed │
└────────────────────────────────────────────────┘
Conversion Examples
Original Option Value → Handleized Tag Component
─────────────────────────────────────────────────────────
"Red" → red
"Dark Blue" → dark-blue
"Extra Large" → extra-large
"XL" → xl
"Size 8" → size-8
"Navy/White" → navy-white
Complete variant tag examples:
─────────────────────────────────────────────────────────
Color: "Red", Size: "Small" → variant-red-small
Color: "Dark Blue", Size: "XL" → variant-dark-blue-xl
Color: "Navy/White", Size: "8" → variant-navy-white-8
Image Visibility Matrix
Product has 3 variants: Red/S, Red/M, Blue/S
Images:
┌─────────────────────────────────────────────────────────────┐
│ Image Alt Text │ Red/S │ Red/M │ Blue/S │
├───────────────────────────────────┼───────┼───────┼────────┤
│ "Front variant-red-s" │ ✓ │ ✗ │ ✗ │
│ "Back variant-red-s" │ ✓ │ ✗ │ ✗ │
│ "Model variant-red-s" │ ✓ │ ✗ │ ✗ │
│ "Detail variant-red-m" │ ✗ │ ✓ │ ✗ │
│ "Front variant-blue-s" │ ✗ │ ✗ │ ✓ │
│ "Size chart" (no tag) │ ✓ │ ✓ │ ✓ │
└─────────────────────────────────────────────────────────────┘
Legend: ✓ = Shows ✗ = Hidden
Setup Process Flow
┌──────────────────────────────────────────────────────────────┐
│ STEP 1: Enable Setting │
│ ─────────────────────────────────────────────────────────── │
│ Theme Customizer → Product Media Gallery │
│ → Turn on "Hide unselected variant media" │
└──────────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 2: Determine Variant Identifiers │
│ ─────────────────────────────────────────────────────────── │
│ Red / Small → variant-red-small │
│ Red / Medium → variant-red-medium │
│ Blue / Small → variant-blue-small │
└──────────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 3: Tag Images in Shopify │
│ ─────────────────────────────────────────────────────────── │
│ For each image: │
│ 1. Click image → Edit │
│ 2. Add to alt text: "Description variant-red-small" │
│ 3. Click Done │
└──────────────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────┐
│ STEP 4: Test │
│ ─────────────────────────────────────────────────────────── │
│ View product on storefront │
│ Select different variants │
│ Verify correct images show/hide │
└──────────────────────────────────────────────────────────────┘
Common Patterns
Pattern 1: Color-Only Products
Product: Coffee Mug (Red, Blue, Green)
Images:
Red: variant-red (3 images)
Blue: variant-blue (3 images)
Green: variant-green (3 images)
General: (no tag) (1 image)
Total: 10 images
Pattern 2: Color + Size Products
Product: T-Shirt (Red/Blue × S/M/L)
Images:
Red: variant-red-s (4 images, shows for all Red sizes)
Blue: variant-blue-s (4 images, shows for all Blue sizes)
General: (no tag) (2 images)
Total: 10 images
Pattern 3: Multiple Images Per Exact Variant
Product: Custom Hat (Design A/B × Color 1/2)
Images:
Design A, Color 1: variant-design-a-color-1 (6 images)
Design A, Color 2: variant-design-a-color-2 (6 images)
Design B, Color 1: variant-design-b-color-1 (6 images)
Design B, Color 2: variant-design-b-color-2 (6 images)
Total: 24 images
Troubleshooting Visual
❌ PROBLEM: Images aren't hiding
│
├─ CHECK: Is setting enabled?
│ └─ Theme Customizer → "Hide unselected variant media" = ON
│
├─ CHECK: Correct tag format?
│ └─ Must be: variant-{option1}-{option2}
│
├─ CHECK: Lowercase with hyphens?
│ └─ "variant-Red-Small" ❌ → "variant-red-small" ✓
│
└─ CHECK: Correct option order?
└─ If options are Color then Size:
variant-red-small ✓ (not variant-small-red ❌)
❌ PROBLEM: Wrong images showing
│
├─ CHECK: Typos in tags?
│ └─ variant-rd-small ❌ → variant-red-small ✓
│
└─ CHECK: All images tagged?
└─ Ensure each variant has at least 1 tagged image
❌ PROBLEM: All images disappear
│
└─ CHECK: At least one image per variant
└─ Either tagged OR untagged (general) images needed
Mobile vs Desktop View
DESKTOP MOBILE
┌─────────────────────────┐ ┌─────────────┐
│ [Image Grid] │ │ [Carousel] │
│ ┌───┐ ┌───┐ ┌───┐ │ │ ┌───┐ │
│ │ 1 │ │ 2 │ │ 3 │ │ │ │ 1 │ │
│ └───┘ └───┘ └───┘ │ │ └───┘ │
│ ┌───┐ ┌───┐ ┌───┐ │ │ ● ○ ○ │
│ │ 4 │ │ 5 │ │ 6 │ │ └─────────────┘
│ └───┘ └───┘ └───┘ │ │
└─────────────────────────┘ │
│ │
└────── Same filtering ───────┘
applies on both!
Both views respect variant image tagging!