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. We have also provided a branch of the Dawn theme that incorporates these changes and may be used as a reference.
The key changes that must be made are in how the theme renders option values and loads option value availability.
To support high-variant products, you'll use the following resources:
- The
product_optionobject - The
product_option_valueobject - The
option_valuesparameter 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](/docs/api/section-rendering) 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"Themes have typically iterated through all of a product’s variants to determine option value availability. This is no longer recommended since the variant set might be very large. Instead of needing to load all variants, themes can use the product_option_value.variant object to retrieve only the variants that are associated with the option values that are displayed to the buyer. Initial option value availability should be determined from the variant’s available field, and the Section Rendering API should be used to load subsequent availability states.
If a variant is manually deleted or an option value doesn't exist on all combined listing children, then product_option_value.variant will be null.
Looking at our previous example, we can set an option value’s availability and embed the variant in the page, so that the theme script can read it:
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.
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: