Update a theme to use variant images

Caution

This is an advanced tutorial and is not supported by Shopify. Knowledge of web design languages such as HTML, CSS, Javascript and Liquid is required. We suggest hiring a Shopify Expert if you are not comfortable proceeding with the following tutorial.

Caution

This document has not been verified to work with sectioned themes. We are currently reviewing our documentation and will update them soon. You can try to implement this on your theme, but keep in mind that it may not function.

Variant images is a feature that allows you to associate an image with a variant. This article outlines how to update your theme to take advantage of this feature.

Updating product.liquid to support variant deep-linking

One component of the variant images feature is the ability to deep-link directly to a variant. This is done by appending the ?variant= query parameter to the URL of the product along with the ID of the variant.

For example, if you wanted to link to the "Small" variant of a T-shirt, you could do so through a URL that looks like this:

Here, we are using the product.selected_or_first_available_variant attribute which returns the variant that was deep-linked. If it matches with the variant in the current iteration of the for loop, it will output selected="selected", causing that option in the drop-down to be selected when the template is loaded.

Showing the deep-linked variant's price

In your theme, you may be outputting the price of the variant as follows:

Showing the deep-linked variant's image

To show the deep-linked variant's image in the "featured image" container when the product page is loaded, you must replace the product's featured image with the image of the variant returned by the product.selected_or_first_available_variant attribute.

In your theme, you may be loading the product's featured image like this:

Updating product.liquid to support variant images

In Step 1 we added Liquid code to show the appropriate attributes of the deep-linked variant. However, after the page is loaded, we must update the OptionSelectors Javascript function to update the variant image as the user selects different variants.

Tip

The OptionSelectors function in your theme should already be updating variant attributes such as price, compare_at_price, availability, etc.

Updating the OptionSelectors JavaScript function

The JavaScript for OptionSelectors is typically found in the product.liquid or theme.liquid template. It may also be inside a separate JavaScript file in theme's Theme Assets.

Look for where OptionSelectors is initialized, and add enableHistoryState: true to its parameter, as follows:

Adding this new parameter to the OptionSelectors constructor makes it so that the URL in the browser updates with the ?variant=variant_id query parameter as you select different variants.

Next, we want to have the product page image update with the variant's image as you select different variants. In the selectCallback function, you will likely already have some code that updates the variants' price, compare_at_price, etc. Within the selectCallback function, add the following code: