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.
In this tutorial, you'll learn how to support product variants in your theme.
To support product variants, you'll use the following:
- The
product
object - The
variant
object - The Shopify option selection JavaScript function (optional)
Implementing product variants
Anchor link to section titled "Implementing product variants"To support variants in your theme, you need to implement the following components:
- Variant deep link handling: A variant can be linked to directly, so you should ensure that the product information is updated for the "selected" variant when a variant is referenced in a product link.
- Variant selectors: You should build at least one variant selector to allow customers to easily browse the available variants of a product. Selecting a variant should update the product information.
You might want to add these components to a section that can be included in a JSON product template, or a Liquid product template.
Variant deep link handling
Anchor link to section titled "Variant deep link handling"Variant deep links are product links that contain a ?variant=[variant-id]
query parameter, where [variant-id]
is the ID of the associated variant. This allows you to link directly to a variant. You can add this functionality to a section that can be included in a JSON product template, or a Liquid product template.
When variants are deep-linked, you can access which variant is linked through the selected_variant
attribute of the product
object. However, a product link won't always contain a deep-linked variant. In these cases, you can default to the selected, first available, or first variant through the selected_or_first_available_variant
attribute.
After you identify the variant that you want to display, you need to ensure that the following product elements reflect it:
- Product media
- Product price
- Variant selector
The following example assigns a default variant using product.selected_or_first_available_variant
, populates a basic media and price display based on that variant, and selects that variant in a basic variant selector.
Variant selectors
Anchor link to section titled "Variant selectors"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 can 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.
Variant selectors should be added to a section that can be included in a JSON product template, or a Liquid product template. They can also be included in product grid or product quick view snippets to allow customers to view variants on other pages, like collections.
You can build your own variant selection functionality in JavaScript, or you can use the JavaScript function built by Shopify.
Shopify option selection
Anchor link to section titled "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 do the following:
Add a master selector
Anchor link to section titled "Add a master selector"For the option selection 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.
Add a callback function
Anchor link to section titled "Add a 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:
Your callback should handle the following cases:
- The
variant
exists, and is available - The
variant
exists, and isn't available - The
variant
doesn't exist
A Liquid variant
object is passed to the callback function.
The selector
object passed to the callback function is the calling OptionSelectors
object.
Instantiate the option selection JavaScript
Anchor link to section titled "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 . |