---
title: Variant search
description: How to handle product variants in search results -- expanding or collapsing them.
slug: search/guides/variants
docKind: guide
hub: search
---

If your products contain variants (e.g., different colors or sizes), Luigi's Box can handle them in two distinct ways: by **Expanding** them (showing every variant) or **Collapsing** them (showing only the best match).

:::note
**Deep dive**: For visual examples and detailed implementation guides, see the [Variant search quickstart](/quickstart/search/).
:::

## Search modes

### Expanded variants (flat)

In this mode, every variant is treated as a standalone product. If a user searches for "T-shirt", and you have a Blue, Red, and Green variant, the user will see **three separate tiles**.

- **Pros:** Maximizes shelf space and visibility for all options.
- **Cons:** Can clutter results if you have many near-identical variants (e.g., sizes).
- **Implementation:** Simply index variants as separate items.

### Collapsed variants (grouped)

In this mode, the search engine groups variants under a single "Master" product. The user sees **one tile** -- the one representing the *best matching variant* for their specific query.

- **Pros:** Clean results page; users see the most relevant option.
- **Cons:** Hides other options until the user clicks through.
- **Control:** You can toggle this behavior at query time using the `non_collapsed_variants` parameter.
  - `false` (default for grouped data): Collapse variants.
  - `true`: Expand variants (temporarily revert to flat mode).

See [non_collapsed_variants](/search/api/v2/search/) in the reference.

## Selection logic (best variant)

When collapsing variants, we determine the "representative" variant using this tie-breaking logic:

1. **Relevance score**: The variant that best matches the text query wins (e.g., for query "red", the Red variant wins).
2. **Preference**: If scores are equal, we check the `_variant_preference` attribute (higher is better). You can set this to prioritize specific seasonal items or bestsellers.
3. **Price**: If still tied, the lowest price wins.

## Data requirements

To enable Collapsed Variants, you must index your data with a nested structure or use a grouping identifier.

- **API:** Index [Nested variants](/indexing/data-layout/).
- **Feeds:** Use a [Grouping identifier](/indexing/feeds/).

## Performance

Processing complex variant structures impacts search speed. We recommend keeping the average number of variants per product **below 10**. If you have significantly more (e.g., hundreds), consider if "Searchable Variants" is truly the right tool, or if simple filtering would be more performant.