Skip to main content

​
Overview

Variant breakouts display specific product options (like Stone, Color, or Size) as individual variant tiles instead of a single product tile. A variant breakout 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. Go to Merchandise → 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. The Option attribute 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
Select 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

In the Where it applies card, use the Surface field to select where the variant breakout should be active:
  • Search & Collections (default) — 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
Overlapping breakouts are resolved by scope specificity. The more narrowly scoped breakout owns its products, and broader breakouts run everywhere else. You can safely layer a collection-scoped breakout over a store-wide breakout on the same products. Two breakouts at the same scope tier and on the same surface cannot cover the same products, even if they use different option codes. Layers rejects the save with an error naming the tier and the overlapping product IDs. A search-only breakout and a collections-only breakout never conflict because they run on different surfaces. See Multiple breakouts on the same products for the tier table.
Search results only apply breakouts that target all collections. A collection-scoped breakout with Surface set to Search Only or Search & Collections is skipped in Search. Use a store-wide breakout if you need breakout behavior in Search results.

​
Excluded collections

Optionally select collections the breakout should never run on. Use the Excluded collections field to select one or more collection handles. The breakout skips those collection pages even when they fall inside its targeting. Excluded collections are most useful for store-wide breakouts. Instead of enumerating every collection you want as a target, leave Target collections empty and exclude the few collections that should keep standard product tiles. On an excluded collection page, products covered by the breakout display as single product tiles instead of variant tiles. Example: store-wide Color breakout, except Clearance
  • Target Collections: All collections (empty)
  • Excluded Collections: clearance
Every collection page breaks products out by color, but the “Clearance” collection shows one tile per product.
You cannot list the same collection in both Target collections and Excluded collections. Layers rejects the save with a validation error naming the conflicting handles. Remove the collection from one of the two lists.
Exclusions only apply where a collection context exists. A store-wide breakout with exclusions still runs in Search results. To remove individual variants from the tile grid instead of whole collection pages, use Conditions.
The variant breakouts list shows an Excluded Collections column so you can see each breakout’s exclusions at a glance.

​
Target products

Specify which products should use this breakout:
  • All Products — Leave this field empty to apply the breakout to all products (within the target collections)
  • Specific Products — Select one or more products to target only those products
When you combine product targeting with collection targeting, the breakout uses AND logic: it only applies to the selected products within the selected collections.
Each targeted product must have the breakout’s option. If you add an indexed product that lacks the option (for example, the option was renamed upstream), saving fails with a validation error. Products that are still indexing are allowed through and re-checked automatically once indexing completes. See unresolved targets for how mismatches are surfaced later.
Example use cases:
  • Target a specific product line within a broader collection
  • Create breakouts for featured products while keeping other products as standard tiles
  • Test variant breakouts on a subset of products before rolling out to an entire collection

​
Preview a targeted product

The Preview card shows how a targeted product splits into tiles with the current settings. When you target more than one specific product, a Preview product select appears above the preview. Select any targeted product to see it split into tiles. Switching products reloads the variant tiles immediately. By default the preview shows the first unresolved target if one exists, otherwise the first targeted product. If you remove the previewed product from the targets, the preview falls back to that default. When no products are targeted, the preview samples a product that has the selected option.
Product targeting allows breakouts with the same option code to coexist on the same collections. A breakout with product targeting only applies to those specific products, so it won’t conflict with a breakout without product targeting (which applies to all other products).

​
Conditions

Optionally add conditions that exclude variants from the breakout. Matching variants don’t get their own tile, but their siblings still break out as normal. Use this to keep specific variants out of the tile grid without dropping the whole product from the breakout.
  1. In the Conditions card on the breakout form, click Add condition.
  2. Select a variant-grain attribute. You can select a variant column under variants.* (for example variants.on_sale, variants.inventory_quantity, or variants.compare_at_price), a variant metafield under variant_metafields.* (for example variant_metafields.custom.material, including nested JSON paths like variant_metafields.custom.specs.weight), or a variant option under options.* (for example options.Size or options.Color).
  3. Select an operator and enter a value. Supported operators depend on the field’s value type:
    • Text fields and variant options (options.*): equals, does not equal, is in, is not in, contains, begins with, ends with, is empty, is not empty.
    • Numeric and datetime fields: equals, does not equal, greater than, less than, between, is empty, is not empty.
    • Boolean fields: equals, does not equal, is empty, is not empty.
  4. Add more conditions and switch the combinator between AND and OR to control how they combine.
The live preview greys out any variant that a condition removes so you can confirm the result before saving.
Conditions apply per variant. If every variant of a product matches the exclusion, that product falls through to a single standard product tile instead of breaking out. See Exclusion conditions for more.
Example: hide variants on sale
  • Field: variants.on_sale
  • Operator: equals
  • Value: true
A Color breakout with this condition still breaks out every color that isn’t on sale. The on-sale color is folded back into the parent product tile. Example: hide discontinued variants by metafield
  • Field: variant_metafields.custom.discontinued
  • Operator: equals
  • Value: true
A Style breakout with this condition drops any variant whose custom.discontinued metafield is true, while sibling styles keep breaking out. Variant metafield conditions use the metafield’s declared value type (string, number, boolean, or datetime) to determine which operators are available. Example: hide a specific option value
  • Field: options.Size
  • Operator: equals
  • Value: Small
A Color breakout with this condition still breaks out every color, but variants assigned the “Small” size fold back into the parent product tile. Layers matches the option name against its canonical code, so options.Size and options.size refer to the same option.

​
Target blocks

Choose whether the breakout also applies to block recommendations:
  • Off (default) — Blocks continue to return standard product tiles.
  • On — Blocks return variant tiles for products in scope of the breakout, matching Browse and Search behavior.
Block targeting still respects the breakout’s product and collection targeting. Individual blocks can bypass variant breakouts using the Disable variant breakouts safeguard on the block itself.

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

​
Merchandising rule warnings

When configuring a breakout that applies to collections, the form displays a warning if any merchandising rules have the Disable Variant Breakouts option enabled. The warning lists the affected rule name, collection, and sort order so you know which collection pages will override your breakout. The warning updates automatically as you change the Surface or Collections fields.

​
Save the breakout

When you are ready to save, you have two options:
  • Save Draft — Saves the breakout configuration without making it live. Use this to prepare and review your configuration before activating it.
  • Publish — Saves and immediately activates the breakout. Variant tiles begin appearing in API responses right away.
New breakouts default to draft status, so you can verify the configuration before it affects your storefront.

​
Track propagation after saving

After you save or publish, Layers rebuilds the breakout’s collection scope in the background. A Publishing variant breakout toast with a spinner appears while the rebuild runs, then updates to a Published confirmation once the change has propagated. Only you (the person who made the change) see these toasts. Rebuilds triggered by background syncs don’t show them. The Status badge on the Variant Breakouts list shows the same progression to everyone: Publishing with a spinner while the rebuild runs, Failed if the rebuild fails, and Published once the change is live.

​
What happens next

Once your variant breakout is active:
  1. Products with the option expand into individual variant tiles
  2. Products without the option continue to display as standard product tiles
  3. API responses include a __typename field identifying each tile as "Product" or "Variant"
  4. Total results and facet counts reflect tile counts (not product counts)
  5. Pagination operates 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
  • Surface: Search & Collections
  • Target Collections: rings, gemstone-jewelry
  • Target Products: All products
  • Status: Published
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
  • Surface: Search & Collections
  • Target Collections: All collections
  • Target Products: Amethyst Ring, Rose Quartz Pendant, Tiger Eye Bracelet
  • Status: Published
Configuration 2:
  • Name: Color Breakout
  • Option Attribute: Color
  • Surface: Search & Collections
  • Target Collections: All collections
  • Target Products: Summer Hoodie, Beach T-Shirt, Sunset Joggers
  • Status: Published
Result: In the “New Arrivals” collection, the selected jewelry products are broken out by stone (showing individual gemstone variants). The selected apparel products are broken out by color (showing individual colorway variants). All other products display as standard product tiles.
Both breakouts target all collections, so each one needs its own list of products. Two breakouts at the same scope tier and on the same surface can’t cover the same products, even when they break out different options. If both left Target Products empty, Layers would reject the second one at save time.

​
Product-specific targeting

Goal: Break out only specific premium rings by gemstone in the “Rings” collection, while keeping other rings as standard product tiles. Configuration:
  • Name: Premium Gemstone Breakout
  • Option Attribute: Stone
  • Surface: Search & Collections
  • Target Collections: rings
  • Target Products: Premium Amethyst Ring, Premium Rose Quartz Ring, Premium Tiger Eye Ring
  • Status: Published
Result: Only the three selected premium ring products are broken out into individual gemstone variant tiles. All other rings in the collection display as standard product tiles. Use product targeting to highlight specific products and keep standard tiles for the rest of your catalog.

​
Combining product and collection targeting

Goal: Break out color variants for a specific apparel line only within the “Sale” collection. Configuration:
  • Name: Sale Apparel Color Breakout
  • Option Attribute: Color
  • Surface: Search & Collections
  • Target Collections: sale
  • Target Products: Summer Hoodie, Beach T-Shirt, Sunset Joggers
  • Status: Published
Result: The three selected apparel products are broken out by color, but only when browsing the “Sale” collection. In other collections (like “New Arrivals” or “All Products”), these same products display as standard product tiles. Product and collection targeting combine with AND logic: the breakout applies to selected products AND selected collections.

​
Coexisting breakouts with product targeting

Goal: Create two different color breakouts for different product lines in the same collection. Configuration 1:
  • Name: Premium Apparel Color Breakout
  • Option Attribute: Color
  • Surface: Search & Collections
  • Target Collections: clothing
  • Target Products: Premium Hoodie, Premium T-Shirt
  • Status: Published
Configuration 2:
  • Name: Basic Apparel Color Breakout
  • Option Attribute: Color
  • Surface: Search & Collections
  • Target Collections: clothing
  • Target Products: Basic Hoodie, Basic T-Shirt
  • Status: Published
Result: Both breakouts use the same option code (Color) and target the same collection (clothing), but they don’t conflict because they target different products. The premium products are broken out by the first breakout, and the basic products are broken out by the second breakout. Product targeting creates distinct scopes that don’t overlap.

​
Troubleshooting

  • Verify the breakout is published (not in draft status)
  • 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)
An enabled breakout already covers the collections or products you selected. The validation rules are:
  • Breakouts on different scope tiers can coexist. For example, a breakout with product targeting can coexist with one without product targeting. The more specific one wins for its products, and the broader one covers everything else.
  • Two breakouts that both omit product targeting cannot share a collection scope on the same surface, regardless of option code.
  • Two product-targeted breakouts at the same tier and on the same surface cannot list the same product, regardless of option code. The runtime breaks a product out by a single option code, so the second would silently do nothing.
  • A Search Only breakout and a Collections Only breakout never conflict. A breakout set to Search & Collections conflicts with a same-tier, same-scope breakout on either surface.
To resolve the error, you can:
  • Remove the overlapping product from one of the breakouts.
  • Disable one of the conflicting breakouts.
  • Narrow the target collections so the two breakouts no longer overlap.
  • Split the breakouts by surface: set one to Search Only and the other to Collections Only so they no longer run in the same query.
Multiple breakouts, with the same or different option codes, can target the same collections when they target different products.
Facet counts reflect unique tile counts, not total variant counts. When a product is broken out by an option (e.g., Color), the facet count increases by the number of unique option values, not the total number of variants.Example: A product with 4 variants (Red/S, Red/M, Blue/S, Blue/M) broken out by Color produces 2 tiles (Red, Blue) and contributes 2 to facet counts, not 4.As a result, facet counts match the number of unique tiles displayed in results.
Ensure each variant has its own image assigned in Shopify. Variant breakouts work best when variants have distinct visual representations.

​
Next steps

​
See also