Support product variants

Products can be broken up into a maximum of three options, and a single combination of those options is a variant. For example, if a t-shirt comes in sizes S, M, and L, and colours Black, White, and Red, then S/Black would be a variant of that product.

To support variants, you should consider the following:

Variant deep-links are product links that contain the ?variant=[variant-id] query parameter, where [variant-id] is the ID of the associated variant. This allows you to link directly to a variant.

When variants are deep-linked, you can access which variant is linked through the selected_variant attribute of the product object. However, a variant won't always be deep-linked, so you can reference the selected, first available, or first variant through the selected_or_first_available_variant attribute.

Now that you have a default variant, you need to ensure that the following product elements reflect that:

  • Product media
  • Product price
  • Variant selector

For example:

Variant selection

You can use a single variant selector where each option represents a variant. However, because products can have up to three product options, you might want to present each of these options separately in the UI. To achieve this, you might create the single variant selector described in the previous section as a hidden master selector, and an additional selector for each option. You can then use JavaScript to update the master selector when an option selector is changed.

You can build your own variant selection functionality, however Shopify has a pre-built JavaScript function to help with this.

Shopify option selection

Shopify has a pre-built JavaScript function that creates separate option selectors from a master selector, hides that master selector and updates it when any option selectors are changed, and returns the selected variant to your own callback function.

You can include this functionality in your theme with the following Liquid:

After you include the function, you need to address the following:

The master selector

For this JavaScript function to create option selectors, it needs a master selector to read the variants from. This master selector needs to have an id attribute for the function to reference, as well as an attribute of name=id to be recognized in the product form as the variant ID source.

For example:

The callback function

The callback function is called when any of the option selectors change, giving you the opportunity to update product elements like the media and price. It can be called anything, but it must have the following two parameters:

For example:


The variant object passed to the callback function has the following attributes:

Attribute Description
available Whether the variant has available inventory. Will be true or false.
barcode The variant's barcode.
compare_at_price The variant's compare price in cents, or null
featured_image The variant's featured image.
id The variant's ID.
inventory_management The variant's inventory tracking service.
inventory_policy Whether the variant should continue selling when the inventory level is 0 or less. Will be continue if it should continue selling, or deny if not.
name The product title combined with the variant title, separated by a -. For example, T-Shirt - S/Black.
option1 The value of the first product option.
option2 The value of the second product option, or null.
option3 The value of the third product option, or null.
price The variant's price in cents.
requires_selling_plan Whether the variant requires a selling plan. Will be true or false.
requires_shipping Whether the variant requires shipping. Will be true or false.
selling_plan_allocations An array of selling_plan_allocation objects.
sku The variant's sku, or null.
taxable Whether the variant is taxable. Will be true or false.
title A combination of the option values with / between each. For example, S/Black for a S and Black variant.
weight The variant's weight in grams, or null.

Your callback should handle the following cases:

  • The variant exists, and is available
  • The variant exists, and is not available
  • The variant doesn't exist

The selector object passed to the callback function is the calling OptionSelectors object.

Instantiate the option selection JavaScript

To use the option selection JavaScript, you need to instantiate a new OptionSelectors object with arguments of the id attribute of the master selector, and an object with the following attributes:

Attribute Description
product The product JSON, which can be accessed using the json filter.
onVariantSelected The name of your callback function.
enableHistoryState Determines whether to update the URL with the ?variant query parameter as variants are selected. Can be true or false.

For example: