Issue: In Shopify’s Product Variant settings, Admin supports grouping (groupBy) of variant options and serializes variant images based on that grouping. Themes, however, cannot access the group_by value via the product object.
Impact: If a merchant sets grouping to the 2nd or 3rd option (instead of the 1st), themes have no way to detect which option is grouped, leading to unreliable variant grouping and incorrect image mapping.
Technical note: groupBy indicates which variant option is used to cluster variants; serialized images means images are assigned according to that chosen group.
Evidence: A screenshot of the Admin UI highlights the grouping setting and context.
Status: Reported as a bug with no workaround or fix provided. Resolution pending; requires exposing group_by to themes via the product object or API.
Summarized with AI on December 29.
AI used: gpt-5.
I’ve found a potential issue in Shopify’s Product Variant settings.
In the admin, there is an option where, if a product has more than one variant option, variants can be grouped (groupBy) and variant images are serialized based on that grouping.
However, in theme development, the product object does not expose the group_by value. Because of this, when a merchant adds more than one variant option and sets the grouping to the 2nd or 3rd option (instead of the 1st), the theme has no way to detect which variant option is actually being grouped.
As a result, themes cannot reliably determine variant grouping or correctly map variant images when groupBy is not set to the first option.
You’re absolutely right—this is a real limitation in Shopify’s current product/variant data model, and it’s something theme developers run into fairly often.
What’s happening
In Product Variant settings, Shopify allows merchants to choose which option (1st, 2nd, or 3rd) variants are grouped by.
That groupBy selection is stored internally, but it is not exposed in the Liquid product object or storefront API data.
Themes only receive:
product.options
product.variants
variant-level attributes (options + images)
Because of this, themes must assume grouping is based on Option 1, which breaks image/variant logic when merchants choose Option 2 or 3.
Why this causes problems
Variant image switching becomes unreliable
Swatches and selectors map incorrectly
Custom JS logic can’t know which option controls grouping
Merchants think it’s a theme bug, but it’s actually a platform data gap
Practical workarounds (used by advanced themes)
Until Shopify exposes groupBy, most developers rely on one of these approaches:
Convention-based approach
Enforce grouping on Option 1 and document this clearly for merchants (most stable, least error-prone).
Image–variant inference
Infer grouping by detecting which option values share the same image set (works in simple cases, breaks with mixed images).
Metafield override (recommended)
Store the intended grouping option in a product metafield (e.g. custom.variant_grouping) and let the theme read that explicitly.
Theme editor setting fallback
Add a theme-level setting that defines which option controls image grouping if Shopify data is ambiguous.
Bottom line
This isn’t a mistake in your implementation—it’s a known Shopify limitation. Until groupBy is exposed via Liquid or the Storefront API, themes cannot reliably handle non-Option-1 grouping without custom logic.
If you’re building or maintaining themes at scale, I strongly recommend:
Locking grouping to Option 1 or
Adding a metafield-based control so merchants don’t accidentally break variant behavior
If you’d like, I can help design a future-proof variant architecture that avoids these edge cases and keeps merchants from running into this issue again.
