Configuration & behavior

​

Configuration options

​

Applies to

Control where your variant breakout is active:

• Both - 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)

This allows you to have different display strategies for search versus browse experiences.

​

Target collections

You can configure variant breakouts to apply:

• To all collections - Leave the target collections field empty
• To specific collections - Select one or more collection handles

When more than one enabled breakout can apply to a product, Layers picks the winner by scope specificity. The most narrowly scoped breakout owns the product, and broader breakouts remain the fallback for anything the narrower breakout does not cover. A collection-scoped breakout can layer on top of a store-wide breakout on the same products without a conflict. The collection-scoped one owns its collection, and the store-wide one keeps working everywhere else. Only same-tier scopes on the same surface conflict at save time. See Multiple breakouts on the same products for the tier table and the full validation rules.

​

Target products

You can optionally configure variant breakouts to apply only to specific products:

• To all products - Leave the target products field empty (default)
• To specific products - Select one or more products

AND logic with collections: When you combine product targeting with collection targeting, the breakout only applies to the selected products within the selected collections. For example, if you target products A and B in collection “clothing”, the breakout only affects those two products when browsing the “clothing” collection. Coexistence with same option code: Product targeting allows multiple 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) or with another breakout targeting different products.

​

Exclusion conditions

Attach conditions to a breakout to exclude variants that match them. Conditions accept three kinds of variant-grain fields. Use variant fields (variants.*) such as variants.on_sale, variants.inventory_quantity, or variants.compare_at_price. Use variant metafields (variant_metafields.*) such as variant_metafields.custom.material, including nested JSON paths like variant_metafields.custom.specs.weight. Use variant options (options.*) such as options.Size or options.Color to match on the option value a variant is assigned. Rules combine with an AND/OR combinator across a single flat list. Nested groups aren’t supported. Matched variants don’t produce a tile:

• Sibling variants still break out for their option values.
• If every candidate variant matches the exclusion, the product falls through as a single standard product tile.
• Exclusions run in Browse, Search, blocks (when block targeting is on), and facet counts.

Common examples:

• Break out Color, except variants.on_sale = true.
• Break out Size, except variants.inventory_quantity <= 0.
• Break out Metal, except variants.compare_at_price below a floor.
• Break out Style, except variant_metafields.custom.discontinued = true.
• Break out Color, except options.Size = 'Small' to hide the small size while every other size still tiles out.

Variant metafield conditions use the metafield’s declared value type (string, number, boolean, or datetime) to determine which operators are available. Metafield codes that are restricted from filtering are rejected at save time. Unknown metafield codes that haven’t been indexed for the store are also rejected. Variant option conditions (options.*) treat values as strings and support equals, does not equal, is in, is not in, contains, begins with, ends with, is empty, and is not empty. Layers matches the option name against the option’s canonical code, so options.Size and options.size refer to the same option. Options that don’t exist on the store’s catalog are rejected at save time.

​

Target blocks

Control whether the breakout also applies to block recommendations:

• Off (default) — The breakout only affects Browse and Search results. Blocks continue to return standard product tiles.
• On — Blocks return variant tiles for products in scope of the breakout, matching the behavior on Browse and Search.

Block targeting respects the breakout’s product and collection targeting. A block only receives variant tiles when its anchor context (product or collection) falls within the breakout’s scope. Individual blocks can override this with the Disable variant breakouts safeguard — see Rules & safeguards.

​

Include option value in title

Control whether variant tile titles include the option value:

• 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 is configurable per breakout, allowing you to customize title formatting based on your catalog structure and customer preferences. Enable this when the option value provides meaningful context; disable it when the product title already includes sufficient variant information or when you prefer a cleaner display.

​

Out-of-stock behavior

Variant breakouts respect your store’s out-of-stock settings at the individual tile level:

​

Hiding out-of-stock variants

When you disable Show out-of-stock products, Layers completely hides out-of-stock variant tiles from results, even if the parent product has other in-stock variants. Only variant tiles with available inventory appear.

​

Demoting out-of-stock variants

When you enable Demote out-of-stock products (and showing out-of-stock is also enabled), Layers pushes out-of-stock variant tiles to the end of results. In-stock variant tiles maintain their normal sort order among themselves.

​

Sell-out pin behavior

When Delete Pins on Sell Out is enabled on a merchandising rule, a pinned product is only unpinned when all of its variants are out of stock. If at least one variant still has inventory, the pin remains active.

​

Pinning variant tiles

Merchandising rules support pinning individual variant tiles to specific positions. When creating a pin in a merchandising rule, you can choose between:

• Product pin - Pins the entire product (or the product tile for non-breakout products)
• Variant pin - Pins a specific variant tile to a position

Variant pins allow you to control exactly which variant appears in a specific position on the collection page. For example, you can pin the “Rose Quartz” variant of a ring to position 1 and the “Amethyst” variant of the same ring to position 3.

​

Similar product search

Layers does not apply variant breakouts to similar product searches. When you use the Similar Products API, results always return standard product tiles regardless of your variant breakout configuration. This keeps similar product recommendations at the product level.