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 colors 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.

Resources

To support product variants, you'll use the following:

• The product object
• The variant object

Implementing product variants

To support variants in your theme, you need to implement the following components:

• Variant deep link handling
• Variant selectors

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 access a variant to the selected, first available, or first variant through the selected_or_first_available_variant attribute of the product object. When variants are deep-linked, the selected_or_first_available_variant attribute will return the variant of the deep-linked.

After you identify the variant that you want to display, you need to ensure that the following product elements reflect it:

• Product price
• Variant selector

Example

The following example assigns a default variant using the 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.

{% assign current_variant = product.selected_or_first_available_variant %}

<!-- Product price -->
<div class="product-detail-price">
  <span>{{ current_variant.price | money }}</span>
  {% if current_variant.compare_at_price > current_variant.price %}
    <span><s>{{ current_variant.compare_at_price | money }}</s></span>
  {% endif %}
</div>

<!-- Variant selector -->
<select name="product-variant">
  {% for variant in product.variants %}
    <option value="{{ variant.id }}" {% if variant == current_variant %}selected{% endif %}>
      {{ variant.title }} - {{ variant.price | money }}
    </option>
  {% endfor %}
</select>

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.

📘

Note

Regardless of the approach you use for variant selection, you need to ensure that when a new variant is selected, the product price are updated to reflect the variant.

You can build your own variant selection functionality in JavaScript.