> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a variant breakout

> Create a variant breakout in Layers to display product variants as individual tiles on collection pages and search results for richer browsing.

## 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. Go 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

<Tip>
  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.
</Tip>

### Applies to

Select 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)

<Note>
  You can use different strategies for search versus browse. For example, show variants in collections but keep products grouped in search results.
</Note>

### 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

<Warning>
  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.
</Warning>

### 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

<Note>
  When you combine product targeting with collection targeting, the breakout uses AND logic: it only applies to the selected products within the selected collections. This allows you to create highly specific breakout configurations.
</Note>

**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

<Tip>
  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).
</Tip>

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

<Tip>
  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.
</Tip>

### 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. This alert 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 **Applies To** or **Target 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 will begin appearing in API responses right away.

<Tip>
  New breakouts default to draft status. This lets you verify the configuration before it affects your storefront.
</Tip>

## 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`
* 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`
* Applies To: `Both`
* Target Collections: All collections
* Target Products: All products
* Status: `Published`

**Configuration 2:**

* Name: `Color Breakout`
* Option Attribute: `Color`
* Applies To: `Both`
* Target Collections: All collections
* Target Products: All products
* Status: `Published`

**Result:** In the "New Arrivals" collection, jewelry products are broken out by stone (showing individual gemstone variants). Apparel products are broken out by color (showing individual colorway variants). Products without either option display as standard product tiles.

### 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`
* Applies To: `Both`
* 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. This allows you to highlight specific products while maintaining a cleaner display 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`
* Applies To: `Both`
* 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. This demonstrates the 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`
* Applies To: `Both`
* Target Collections: `clothing`
* Target Products: `Premium Hoodie`, `Premium T-Shirt`
* Status: `Published`

**Configuration 2:**

* Name: `Basic Apparel Color Breakout`
* Option Attribute: `Color`
* Applies To: `Both`
* 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. This is possible because product targeting creates distinct scopes that don't overlap.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My breakout isn't showing in results">
    * 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)
  </Accordion>

  <Accordion title="I see a validation error about overlapping collections or products">
    Another active breakout with the same option code already targets one or more of the collections and products you selected. The validation rules are:

    * Breakouts with product targeting can coexist with breakouts without product targeting (they target different scopes)
    * Breakouts with the same option code and both having product targeting cannot have overlapping products AND collections
    * Breakouts without product targeting cannot overlap on collections if they use the same option code

    To resolve the error, you can:

    * Use a different option code for your new breakout
    * Add product targeting to create a distinct scope
    * Disable the existing breakout with the same option code
    * Remove the overlapping collections or products

    Note: Multiple breakouts with different option codes can target the same collections and products without conflict.
  </Accordion>

  <Accordion title="Understanding facet counts with variant breakouts">
    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.

    This ensures facet counts match the number of unique tiles displayed in results.
  </Accordion>

  <Accordion title="Variant tiles don't have unique images">
    Ensure each variant has its own image assigned in Shopify. Variant breakouts work best when variants have distinct visual representations.
  </Accordion>
</AccordionGroup>

## Next steps

* [Edit or delete a variant breakout](/help/merchandising/edit-delete-variant-breakout)
* [Pin variant tiles in merchandising rules](/help/merchandising/create-merchandising-rule)
* [Learn more about variant breakouts](/platform/variant-breakouts)

## See also

* [Variant Breakouts Overview](/platform/variant-breakouts)
* [Browse API Documentation](/api-reference/browse)
* [Search API Documentation](/api-reference/search)