Skip to main content

​
Overview

Variant breakouts allow you to configure specific product options (like Stone, Color, or Size) to be displayed as individual variant tiles instead of a single product tile. This is useful when each variant represents a distinct item that customers want to browse and compare independently.

​
Before You Begin

  • Ensure you have products with the option attribute you want to break out (e.g., products with a “Stone” option)
  • Verify that variants have unique images and meaningful differences
  • Consider which collections would benefit from variant breakouts

​
Create a Variant Breakout

  1. Navigate to Merchandising → Variant Breakouts in the dashboard
  2. Click Create Breakout
  3. Configure the breakout settings:

​
Name

Enter a descriptive name for your breakout configuration (e.g., “Stone Breakout” or “Color Breakout for Apparel”).

​
Option Attribute

Select the product option attribute that should trigger the breakout. This dropdown shows all option attributes in your catalog (attributes that start with options.). Examples:
  • Stone - For jewelry with different gemstones
  • Color - For apparel with distinct colorways
  • Size - For products where size represents meaningfully different items
Choose an option where each value represents a distinct item customers want to compare. Avoid options like “Size” for standard clothing where customers typically select size on the product page.

​
Applies To

Choose where the variant breakout should be active:
  • Search & Collections - Applies to both search results and collection browse pages
  • Collections Only - Only applies to collection browse pages (Browse API)
  • Search Only - Only applies to search results (Search API)
You can use different strategies for search versus browse. For example, show variants in collections but keep products grouped in search results.

​
Target Collections

Specify which collections should use this breakout:
  • All Collections - Leave this field empty to apply the breakout to all collections
  • Specific Collections - Select one or more collection handles to target specific collections
You cannot have overlapping collection targets for the same option code. Multiple breakouts with different option codes can target the same collections (including all collections), but breakouts with the same option code cannot overlap. If you try to create a breakout that targets collections already covered by another breakout with the same option code, you’ll receive a validation error.

​
Include Option Value in Title

Control whether variant tile titles include the option value appended to the product title.
  • Enabled (default) - Variant tiles display titles in the format "{product title} - {option value}" (e.g., “Amethyst Ring - Rose Quartz”)
  • Disabled - Variant tiles use the original product title without modification
This setting allows you to customize how variant tiles are displayed based on your catalog structure and customer preferences.
Enable this option when the option value provides meaningful context (e.g., gemstone names, distinct colorways). Disable it when the product title already includes sufficient variant information or when you prefer a cleaner display.

​
Enable/Disable

Toggle the breakout on or off. Disabled breakouts are saved but not applied to results.

​
Save the Breakout

Click Create Breakout to save your configuration. The breakout will be immediately active if enabled.

​
What Happens Next

Once your variant breakout is active:
  1. Products with the option will be expanded into individual variant tiles
  2. Products without the option will continue to display as standard product tiles
  3. API responses will include a __typename field identifying each tile as "Product" or "Variant"
  4. Total results and facet counts will reflect tile counts (not product counts)
  5. Pagination will operate on tiles

​
Example Scenarios

​
Single Option Breakout

Goal: Display rings with different gemstones as individual tiles in the “Rings” collection. Configuration:
  • Name: Gemstone Breakout
  • Option Attribute: Stone
  • Applies To: Both
  • Target Collections: rings, gemstone-jewelry
  • Enabled: Yes
Result: When customers browse the “Rings” collection, they see individual tiles for each gemstone variant (Amethyst Ring, Rose Quartz Ring, Tiger Eye Ring) instead of a single “Ring” product tile.

​
Multiple Option Breakouts in the Same Collection

Goal: Display both jewelry with different gemstones and apparel with different colors as individual tiles in the “New Arrivals” collection. Configuration 1:
  • Name: Gemstone Breakout
  • Option Attribute: Stone
  • Applies To: Both
  • Target Collections: All collections
  • Enabled: Yes
Configuration 2:
  • Name: Color Breakout
  • Option Attribute: Color
  • Applies To: Both
  • Target Collections: All collections
  • Enabled: Yes
Result: In the “New Arrivals” collection, jewelry products are broken out by stone (showing individual gemstone variants), while apparel products are broken out by color (showing individual colorway variants). Products without either option display as standard product tiles.

​
Troubleshooting

  • Verify the breakout is enabled
  • Check that you’re viewing a collection or search result where the breakout applies
  • Ensure products in the collection have the specified option attribute
  • Confirm the option attribute name matches exactly (case-sensitive)
Another active breakout with the same option code already targets one or more of the collections you selected. You must either:
  • Use a different option code for your new breakout
  • Disable the existing breakout with the same option code
  • Remove the overlapping collections from one of the breakouts with the same option code
  • Use different collection targets for breakouts with the same option code
Note: Multiple breakouts with different option codes can target the same collections without conflict.
This is expected behavior. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. A product with 5 variants will contribute 5 to the facet count.
Ensure each variant has its own image assigned in Shopify. Variant breakouts work best when variants have distinct visual representations.

​
Next Steps

​
See Also