Show Variant Image Swatches Under Shopify Collection Cards

Show Variant Image Swatches Under Shopify Collection Cards

A collection page should help customers compare products without opening every product individually.

For clothing, furniture, and accessories, small variant photos beneath each product card can make that browsing experience much clearer. Customers can immediately see that a chair comes in three finishes or that a shirt is available in several patterns.

The challenge is adding those thumbnails without duplicating every size, breaking card links, or loading dozens of unnecessary images.

The most reliable starting point is a small, server-rendered row of image links. Each thumbnail opens the appropriate product variant. In-card image switching can come later if the theme supports a coordinated implementation.

This guide covers both approaches and explains where custom code needs to respect the existing theme.

  1. Decide what clicking a swatch should do

There are two common interaction models.


Variant navigation:
Click a thumbnail to open that product variant.

In-card preview:
Click a thumbnail to update the current card
without leaving the collection.

Variant navigation is simpler. It works without JavaScript and does not require synchronizing the card’s price, availability, and quick-add state.

In-card preview offers a richer browsing experience, but changing the photo alone can produce misleading results.

For example:


Preview image:
Premium leather finish.

Displayed price:
Starting price for the fabric version.

Quick-add selection:
Default fabric variant.

Those elements no longer describe the same selection.

My recommendation is to start with variant links unless the theme already provides a complete card-level variant selector.

  1. Check whether the theme already supports the feature

Inspect the theme’s collection grid and product-card settings before adding code.

Look for options related to swatches, variant selectors, color options, or product-card media. The available settings depend on the theme and version.

Also distinguish these features:


Color swatch:
A color chip.

Option swatch image:
An image associated with an option value.

Variant photo thumbnail:
The product image assigned to a specific variant.

A theme can support one without supporting all three.

A second image on hover is another separate feature. It does not necessarily provide a selectable image for each color or material.

If the existing implementation meets the requirement, use it rather than adding a second selector beneath it.

  1. Prepare the variant images first

Shopify allows one assigned image per variant. Variants do not support videos or 3D models as their assigned image.

For a useful collection-card selector, assign representative photos consistently.

For example:


Black / Small:
Black product photo

Black / Medium:
Same black product photo

Cream / Small:
Cream product photo

Cream / Medium:
Same cream product photo

That consistency lets a simple implementation display one thumbnail per distinct assigned image instead of repeating the same photo for every size.

Do not confuse the entire product gallery with variant images. Looping over every product image can include lifestyle photos, size charts, and packaging images that do not represent selectable variants.

  1. Choose a deduplication strategy

Decide whether the row represents unique photographs or unique option values.


Image-based grouping:
One thumbnail per distinct assigned image.

Option-based grouping:
One thumbnail per color, finish, or other chosen option.

Image-based grouping is a useful starting point, but it has limitations.

Two different colors sharing one image will collapse into one thumbnail. Conversely, different photographs assigned to sizes of the same color can create several thumbnails for that color.

For exact color grouping, build around the intended option and select a representative variant for each value. Define whether that representative should prefer an available size.

Do not assume that color is always the first option or that every product uses the English option name “Color.”

  1. Integrate with the product card, not the collection loop alone

Find the component responsible for rendering an individual product card.

A theme might use a snippet named card-product.liquid, but names and architecture vary. Treat that as an example, not a universal file path.

The swatch row should sit inside the card’s layout but outside any existing product anchor.

Conceptually:


<article class="product-card">
  <!-- Existing product image link -->

  <!-- Existing title and price -->

  <!-- Variant image links -->

  <!-- Existing quick-add interface -->
</article>

Do not place thumbnail links inside another link. Nested anchors are invalid HTML and can cause unpredictable click behavior.

Also inspect full-card click overlays. A stretched product link can intercept clicks intended for the swatches. Fix the interaction structure rather than applying a large z-index without understanding it.

  1. Render a small row of unique variant-image links

The following Liquid example illustrates a navigation-based implementation.

It assumes that the current product is available as card_product. Adapt that variable to the theme.


{% liquid
  assign swatch_limit = 4
  assign swatch_count = 0
  assign seen_images = '|'
%}

{% capture variant_swatches %}
  {% for variant in card_product.variants %}
    {% if variant.featured_image != blank %}
      {% assign image_key = variant.featured_image.id
        | prepend: '|'
        | append: '|'
      %}

      {% unless seen_images contains image_key %}
        {% assign seen_images = seen_images
          | append: variant.featured_image.id
          | append: '|'
        %}

        {% assign swatch_label = card_product.title
          | append: ' — '
          | append: variant.title
        %}

        <li class="variant-photo-swatches__item">
          <a
            class="variant-photo-swatches__link"
            href="{{ variant.url | escape }}"
            aria-label="{{ swatch_label | escape }}"
          >
            {{
              variant.featured_image
              | image_url: width: 88
              | image_tag:
                widths: '44, 88',
                sizes: '44px',
                loading: 'lazy',
                alt: ''
            }}
          </a>
        </li>

        {% assign swatch_count = swatch_count | plus: 1 %}

        {% if swatch_count >= swatch_limit %}
          {% break %}
        {% endif %}
      {% endunless %}
    {% endif %}
  {% endfor %}
{% endcapture %}

{% if swatch_count > 1 %}
  <ul class="variant-photo-swatches">
    {{ variant_swatches }}
  </ul>
{% endif %}

This example:

  • Uses assigned variant images.
  • Deduplicates by image ID.
  • Limits the rendered row to four images.
  • Links to representative variants.
  • Hides the row when fewer than two distinct images are found.

It is not an exhaustive color selector. It also does not preferentially choose an available variant when several variants share an image. The first matching variant supplies the link.

Translate the accessible label structure for multilingual stores.

  1. Keep the styling scoped

Add styles to an appropriate theme stylesheet rather than repeating a style block for every card.


.variant-photo-swatches {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
  margin: 0.75rem 0 0;
  padding: 0;
  list-style: none;
}

.variant-photo-swatches__item {
  flex: 0 0 auto;
}

.variant-photo-swatches__link {
  display: block;
  width: 44px;
  height: 44px;
  padding: 2px;
  border: 1px solid #767676;
  border-radius: 6px;
  background: #fff;
}

.variant-photo-swatches__link img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: 3px;
}

.variant-photo-swatches__link:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 3px;
}

These class names belong to this example. They are not built-in Shopify selectors.

Adjust colors and dimensions to fit the theme and verify their contrast. If image cropping hides important product details, use a different crop strategy or object-fit: contain.

Avoid broad selectors such as .card img, which can unintentionally resize the main product image and unrelated cards.

  1. Handle sold-out options deliberately

Choose what the swatch row should communicate.

You might show all represented finishes, show only available choices, or retain sold-out choices with a clear availability indication.

Do not assume that one unavailable size means the entire color is unavailable.


Black / Small:
Unavailable

Black / Medium:
Available

Color-level conclusion:
Black still has an available purchasing option.

For a color-level selector, availability should be evaluated across the relevant combinations.

The example above does not perform that grouping. If an available representative is required, extend the selection logic or use the theme’s existing option-value implementation.

Avoid hiding useful choices accidentally through a simplistic availability filter.

  1. Treat in-card preview as a separate enhancement

If clicking should update the main card image, integrate with the theme’s card behavior rather than attaching a global image replacement script.

A complete preview implementation may need to coordinate:


Main image and responsive sources
Image alternative text
Product destination
Selected-option indicator
Price and compare-at price
Availability
Quick-add variant
Secondary hover image

Changing only src can fail when an existing srcset still points to other images.

Changing only the photo can also leave quick-add connected to the original variant.

Keep a clear interaction contract. Use links for navigation and buttons for an action that stays on the page. Do not make the first tap silently select a variant and the second tap navigate unless the interface clearly explains that behavior.

For a simple photo preview, label it as a preview rather than implying that the purchasing selection has changed.

  1. Support collection filtering and dynamically replaced cards

Many themes replace collection-grid markup when customers filter, sort, or load more products.

Navigation-only swatches are resilient because the links arrive with the rendered card markup and need no event binding.

JavaScript enhancements require more care.

A listener attached only to the initial set of cards may stop working after a filter update. Reinitializing without cleanup can create duplicate listeners.

Use the theme’s established component lifecycle, an appropriately scoped delegated listener, or another compatible initialization pattern.

Test filtering and pagination explicitly. A feature that works only on the first collection load is not finished.

  1. Limit image and rendering overhead

Small thumbnails should request small images.

The example uses image widths suitable for a 44-pixel display rather than requesting full-size product photography.

Other useful safeguards include limiting visible choices, avoiding a JavaScript library for a simple link row, and not making a separate product-data request for every card.

Do not preload every variant image.

Lazy loading can help secondary images, but avoid indiscriminately applying it to the collection’s important above-the-fold product imagery. Shopify’s performance guidance warns against lazy-loading the image responsible for Largest Contentful Paint.

Also consider the markup and Liquid workload. A swatch limit reduces output, but finding unique images can still require iterating through many variants.

Shopify documents a maximum of 250 variants returned by unpaginated product.variants. Therefore, a basic loop must not be presented as an exhaustive solution for high-variant products.

For those catalogs, consider curated card swatch data or an implementation designed around the intended option values.

  1. Handle overflow without misleading counts

Four visible thumbnails do not necessarily mean four total colors.

If you show an overflow control, calculate the count from the same grouping model used by the swatches.


Correct:
Four visible color values plus three additional colors.

Incorrect:
Four thumbnails plus a count based on every size variant.

If the implementation does not calculate the total reliably, use a simple product link such as “View options” instead of an inaccurate “+12.”

For a compact mobile card, a limited row with a clear options link is often easier to use than a tiny carousel.

  1. Test the card as a complete component

Test products with one image, several colors, multiple sizes, missing variant images, shared photographs, mixed availability, and different variant prices.

Then test the collection itself.

  • Click a thumbnail and confirm the intended variant opens.
  • Check keyboard focus and accessible link names.
  • Verify that thumbnails do not trigger the main card link.
  • Test narrow screens and long product titles.
  • Confirm quick-add behavior remains correct.
  • Filter, sort, and paginate.
  • Compare network requests and layout movement before and after.
  • Check other places that reuse the same card component.

A shared product-card change can also affect search results, recommendations, and featured collections. Scope the feature if it should appear only in certain contexts.

  1. Keep the customization maintainable

Keep the swatch rendering small and separate where the theme architecture allows it.

Document the product variable, grouping model, thumbnail limit, availability behavior, and any JavaScript integration.

Preserve the original theme version or a clean code diff. After a theme update, check whether the card structure or event lifecycle has changed before reapplying the customization.

Do not replace the entire product-card component just to insert a thumbnail row. A small integration is easier to review and less likely to disrupt existing behavior.

The recommended approach

Start with a limited row of variant-image links beneath each product card. Deduplicate intentionally, request appropriately sized images, and keep links outside existing card anchors.

Only add in-card preview after defining how the image, price, availability, and quick-add selection remain consistent.

The best swatch row makes choices clearer without turning a collection page into dozens of miniature product forms.

Back to blog

Leave a comment