Supporting Product Variants​

A product can have a maximum of three choices, and when combined, these choices create a variant. For instance, if a T-shirt is available in sizes Small, Medium, and Large, and colors Blue, Red, and White, then Small/Blue would be a variant of that product.

In this tutorial, you will learn how to support product variants in your theme.

Resources​

To support product variants, you will utilize the following:

• product object
• variant object

Implementing Product Variants​

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

• Variant Deep Link Handling: A variant can be directly linked to, so you should ensure that when referencing a variant in a product link, the product information for the "selected" variant is updated.
• Variant Selectors: You should create at least one variant selector to let customers easily browse through available product options. When a variant is selected, it should update the product information.

You might want to add these components to a section that can be included in JSON product templates or HTML product templates.

Variant Deep Link Handling​

Variant deep links are product links that include the ?sku=[sku-id] query parameter, where [sku-id] is the ID of the associated variant. This allows you to directly link to a variant. You can add this functionality to a section that can be included in JSON product templates or HTML product detail templates.

When a variant is deep linked, you can access which variant was linked to through the selected_variant property of the product object. However, a product link won't always include a variant from a deep link. In those cases, you can default to the selected, first available, or first variant using the selected_or_first_available_variant property.

Once you've determined the variant to display, you need to ensure the following product elements reflect it:

• Product media
• Product price
• Variant selector

Example​

The following example assigns a default variant using product.selected_or_first_available_variant, populates basic media and price displays based on that variant, and selects that variant in a basic variant selector.

{{ assign 'current_product_variant' product.selected_or_first_available_variant }}
{{ assign 'product_featured_media' current_product_variant.featured_media }}
<!-- Product media -->
{{#case product_featured_media.type }}
  {{#when 'image' }}
    <div class="product__media"
      style="padding-top: {{ times (divide 1 product_featured_media.aspect_ratio) 100 }}%;"
      data-media-id="{{ product_featured_media.id }}"
    >
      {{ image_tag (image_url product_featured_media width=1000) }}
    </div>
  {{/when}}
  {{#when 'external_video'}}
    <div class="product__media"
      style="padding-top: {{ times (divide 1 product_featured_media.aspect_ratio) 100 }}%;"
      data-media-id="{{ product_featured_media.id }}"
    >
      {{ external_video_tag product_featured_media }}
    </div>
  {{/when}}
  {{#when 'video'}}
    <div class="product__media" data-media-id="{{ product_featured_media.id }}">
      {{ video_tag product_featured_media controls="controls"}}
    </div>
  {{else}}
    <div class="product__media"
      style="padding-top: 100%;"
      data-media-id="{{ product_featured_media.id }}"
    >
      {{ media_tag product_featured_media }}
    </div>
  {{/when}}
{{/case}}
<!-- Product price -->
<div class="product-price">
  <span class="regular-price">{{ money current_product_variant.price }}</span>
  {{#if current_product_variant.compare_at_price '>' current_product_variant.price }}
    <span class="sale-price"><s>{{ money current_product_variant.compare_at_price }}</s></span>
  {{/if}}
</div>
<!-- Variant selector -->
<select name="product-id">
  {{#for product.variants as |variant| }}
    <option value="{{ variant.id }}"
      {{#if variant == current_product_variant }}selected="selected"{{/if}}
    >
      {{ variant.title }} - {{ money variant.price }}
    </option>
  {{/for}}
</select>

Variant Selectors​

You can use a single variant selector where each choice represents a variant. However, since products can have up to five product options, you might want to display these options separately in the user interface. To achieve this, you can create a single variant selector as a hidden master selector and create additional selectors for each option. Then, when an option selector is changed, you can update the master selector using JavaScript.

Variant selectors should be included in a section that can be integrated into JSON product templates or HTML templates. They can also be incorporated into product grids or quick view snippets to enable customers to see variants on other pages, like collections.