Variant 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).
Deep Dive: For visual examples and detailed implementation guides, see the Variant Search Quickstart.
Search Modes
1. 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.
2. 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 (e.g., "Blue T-shirt" behaves like a dedicated result for a "blue" query).
- Cons: Hides other options until the user clicks through.
- Control: You can toggle this behavior at query time using the
non_collapsed_variantsparameter.-
false(default for grouped data): Collapse variants. -
true: Expand variants (temporarily revert to Mode 1).
-
See non_collapsed_variants in the reference.
Selection Logic (Best Variant)
When collapsing variants, we determine the "representative" variant using this tie-breaking logic:
- Relevance Score: The variant that best matches the text query wins (e.g., for query "red", the Red variant wins).
- Preference: If scores are equal, we check the
_variant_preferenceattribute (higher is better). You can set this to prioritize specific seasonal items or bestsellers. - 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.
- Feeds: Use a Grouping Identifier.
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.