Support high-variant products

Themes have historically used the Liquid API to load all of a product's variants when rendering a product. However, with the introduction of increased variant limits, this approach is no longer performant. The performance impact can be even more significant for combined listing products, since they can far exceed the increased product variant limit. You must therefore make several changes in order to support these features.

In this guide, you'll learn how to update your theme to support products with a high number of variants. You can also refer to Dawn's main product section for an example implementation.

The key changes that must be made are in how the theme renders option values and loads option value availability.

Resources

Anchor link to section titled "Resources"

To support high-variant products, you'll use the following resources:

The product_option object
The product_option_value object
The option_values parameter for products rendered using the Section Rendering API

Rendering option values

Anchor link to section titled "Rendering option values"

Themes should use product.options_with_values to render options, and the product_option.values array to render option values.

The product_option_value object provides the following values to simplify rendering:

Field	Application
`id`	Option value IDs should be used with the Section Rendering API when re-rendering the option values section.
`variant`	The variant’s availability field may be used to indicate whether an option value is purchasable.
`selected`	Selected indicates whether the option value is selected.
`product_url`	The URL of the product associated with this option value. Used by combined listings products to signal to the theme that another product’s content should be loaded.

Option value availability

Anchor link to section titled "Option value availability"

Iterating over all product variants to determine option value availability is inefficient for large variant sets. Instead, you can determine availability by using product_option_value.available or variant.available. Using product_option_value.available results in a top-down UX where option values are treated as a tree, and an option value is available if any part of the subtree is purchasable. Using variant.available results in an adjacent UX where option values are treated as graph nodes, and an option value is available if the node is purchasable.

Building on the previous example, you can set an option value’s availability:

When a buyer selects an option value, themes may load the next option value availability state by passing the selected option value IDs to the Section Rendering API:

Supporting combined listings

Anchor link to section titled "Supporting combined listings"

To support combined listings, themes must contain logic to load product information when switching between sibling products.

For example, a shop has a combined listing Pants with child products Pants - red and Pants - green. If a buyer lands on Pants and changes the color, the UI should be updated to display information from the corresponding child product, such as price, images, and description. You can do this with the product_option_value.product_url property when you make a request to the Section Rendering API.

Example

Anchor link to section titled "Example"

Putting it all together, a theme can load a minimal set of variants using the product_option_value.variant object, use the Section Rendering API to load the next availability state by passing the new option value selection, and support combined listings by replacing product content when a buyer switches to a sibling product. The following is a minimal example: