How to Display Product Images Based on Selected Variants

This new feature allows you to automatically display only relevant product images when customers select a specific variant. When enabled, the system will match your product variant names with image alt text to show only the appropriate images.

About “Display Product Image by Selected Variant” Feature

This feature allows you to control which product images appear when a customer selects a specific variant.
When enabled, GemPages automatically displays only the images relevant to the chosen variant by matching the variant name with the image’s alt text.

You can apply this setting to both Product elements and Product List elements.

How the Feature Works

When a visitor selects a product variant, GemPages will:

Compare the variant name with each image’s alt text in your Shopify product.
Display only images that include the variant name in their alt text.
Hide unrelated images automatically.

You can also mark certain images to appear across all variants by adding the keyword “all-variants” in their alt text (e.g., care instructions, size chart).

By default, all product images are shown. You’ll need to enable this option manually as guided below.

How to Enable “Display Product Images by Selected Variant” in GemPages

Follow the steps below to enable this feature inside the GemPages Editor:

Step 1: From your Shopify Admin, go to Apps > GemPages, then open the page that contains your Product element.

Step 2: Click on your Product element to select it. In the Layer panel, find and click on the Product Image element inside it.

Step 3: In the left sidebar, under the Settings tab, scroll down to find Display condition.

Step 4: Choose the display option

You will see two options:

All images (default): displays all product images regardless of variant.
Selected variant: displays only the images that match the selected variant based on their alt text.

Select the Selected variant to enable the feature.

Step 5: Once enabled, click Save and Publish your page.
Your product images will now dynamically update whenever a visitor selects a different variant.

How to Set Up Alt Text for Variant-Based Images in Shopify

To make this feature work correctly, you’ll need to assign proper alt text to each product image in Shopify. GemPages uses this alt text to determine which images belong to which variant.

Step 1: From your Shopify admin, go to Products > [Your Product].

Step 2: Find the images you want to assign to a variant.

Step 3: Click on an image → click Add alt text → enter the variant name.

To ensure the system correctly identifies variant-based images, follow these naming rules for alt text:

All text is converted to lowercase.
Spaces, hyphens (-), and underscores (_) are ignored.
The variant name must appear in the alt text.
To display an image for all variants, include “all-variants” in the alt text.
Use descriptive text for accessibility and SEO purposes.
Maintain consistent naming conventions across your store. Click Save once you’re done, and repeat this for all product images.

Good examples

Cotton T-Shirt Navy Blue Front
Leather Jacket Black Side View
Running Shoes Red Size 10
Product care instructions all-variants

Poor examples

IMG_1234 (no variant information)
Product photo (too generic)

For more detailed information about managing product images and alt text in Shopify, visit:

Shopify Help Center – Product Media

Shopify Help Center – Add Alt Text

Notes:

Featured Image Behavior: When the “Selected variant” option is enabled, GemPages determines the featured image based on the first image whose alt text matches the selected variant name. This means the featured image shown in GemPages might not be the same as the “featured image” you manually assigned to that variant inside Shopify.
Disabled by Default: The “Selected variant” option is off by default. All images will display normally until you enable the feature manually.

Frequently Asked Questions

1. Why are my product images not dissplaying correctly when selecting a variant?

If your images aren’t updating based on the selected variant, try the following steps:

Make sure each product image includes the correct variant name in its alt text.
Check that the “Selected variants” option is activated in the Product Image settings.
Remember that spaces, hyphens (-), and underscores (_) are ignored during matching.
If no image matches the variant name, GemPages will automatically display all product images instead.

2. How can I show certain images for all product variants?

If you want an image (such as a size chart, care guide, or general product shot) to appear for every variant, simply add “all-variants” to its alt text in Shopify.
GemPages will then always display that image, regardless of which variant the customer selects.

3. Can I disable the “Display Product Images by Selected Variant” feature?

Yes. To turn it off, open the Product Image element settings in GemPages Editor and uncheck the “All images” option.
Once disabled, all product images will be shown again by default, regardless of the selected variant.

4. What happens if there are no matching images for a variant?

If no image alt text matches the selected variant, GemPages will automatically display all available product images.

What did you think about this content?

Your comments

Irrelevant: Unexpected or off-topic information.

Inaccurate: The information doesn’t match the product.

Needs small fixes: There are typos or broken links.

I have suggestions: I’d like to suggest improvements for this page.

Email*

Invalid email address.

Something went wrong. Please try again later.

By submitting your email address and comments, you consent to the collection and use of your information as outlined in our Privacy Policy and agree to our Terms of Service.