5lb Fruiting Block

5lb Fruiting Block


Depending on the collection viewed we want to display a different image on the collection products. It is a commune case, some products can be used in different ways or can have multiple variants. When seeing a collection it makes sense for the user to see the appropriate image. This improves the user experience and provide a better way of showcasing your products.


White chairs collection showing default featured product image
Black chairs collection showing matched variant product image

The Logic

  1. Match the collection by its handle. On that collection we will show different product images.
  2. Find the custom variant/image based on an option name and option value.
  3. Modify the collection product item markup to use the matched variant.

The scenario

  • We have 2 collections: white chairs and black chairs.
    Both collections fully or partial contain the same products.
  • On white chairs collection we want to show the featured product image.
    On black chairs collection we want to show the black product variant image.
  • Clicking on a product from black collection should lead to the black variant.
    Clicking on a product from the white collection should lead to the default variant.
  • Our products have both white and black variants and have images assigned.
    Product configuration—the black chairs collection will use the black variant image

Matching the collection

Find your collection Liquid code. Usually you can find the collection code in
templates/collection.liquid or sections/collection-template.liquid

In the collection Liquid code you need to identify the code that generates the product item.
In most cases this is what you are looking for: {% include 'product-grid-item' %}

We want to match the black products collection, we can match it by its handle: 

{%- if collection.handle == 'black-chairs' -%}
  {% include 'product-grid-item' with custom_option_name: 'color', custom_option_value: 'black' %}
{%- else -%}
  {% include 'product-grid-item' %}
{%- endif -%}

If the collection handle is "black-chairs" and we pass 2 variables:
custom_option_name: 'color' and custom_option_value: 'black'

We will use these variables later on to find in product-grid-item the first variant that has the option name "color" and the option value "black".

Finding the desired variant/image

{%- assign featured_image = product.featured_image  -%}
{%- assign product_url = product.url -%}

{%- if custom_option_name != blank and custom_option_value != blank -%}
  {%- assign custom_option_name = custom_option_name | downcase | strip -%}
  {%- assign custom_option_value = custom_option_value | downcase | strip -%}

  {%- for product_option in product.options_with_values -%}
    {%- assign option_name = product_option.name | handle -%}
    {%- if option_name == custom_option_name -%}
      {%- assign option_values = product_option.values | join: ',' | downcase | split: ',' -%}
      {%- for option_value in option_values -%}
        {%- if option_value == custom_option_value -%}
          {%- assign custom_variant = product.variants[forloop.index0] -%}
          {%- if custom_variant.featured_image -%}
            {%- assign featured_image = custom_variant.featured_image -%}
            {%- assign product_url = custom_variant.url -%}
          {%- endif -%}
          {% break %}
        {%- endif -%}
      {%- endfor -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}

If the collection handle is "black-chairs" we will look into the product options for the first variant that has the option name "color" and the option value "black".

If the match is found featured_image and product_url will have the values pulled from that matched variant instead of the default product. We need to modify product-grid-item to use those new variables instead.

Replacing product-grid-item variables

The next part can be tricky, you need to replace the references of:
product.featured_image to featured_image
product.url to product_url

original code

<a href="{{ product.url | within: collection }}" class="product__image-wrapper" title="{{ product.title | escape }}">
  <img src="{{ product.featured_image.src | img_url: 'grande' }}" alt="{{ product.featured_image.alt | escape }}">


<a href="{{ product_url | within: collection }}" class="product__image-wrapper" title="{{ product.title | escape }}">
  <img src="{{ featured_image.src | img_url: 'grande' }}" alt="{{ featured_image.alt | escape }}">

Helper files

To better understand the code changes required, you can have a look at the modified the files of Shopify Simple theme: