Everything, in the order you meet it

What the app does, and when it is the wrong app

Rubik Combined Listings groups products that already exist in your catalogue and links them on the storefront with swatches. A shopper on the navy jumper sees a row of the other colours, clicks sand, and lands on the sand product. Each colour keeps its own URL, its own title and description, its own images and its own stock.

That last sentence is the whole reason to use it. Merchants split colours into separate products on purpose, usually for search, sometimes for inventory or for a supplier feed. The cost of that decision is that a shopper has no way to see the family. This app pays that cost back without undoing the decision.

When it is the wrong app

• Your colours are already variants of one product. Then you do not need grouping, you need the gallery to react to the variant picker. That is Rubik Variant Images, a different app of ours.
• You want one product split into several collection cards. That is the opposite operation, and Stamp does it. It is on our partners page.
• You want to merge products into one real product. Nothing here writes to your catalogue. If you genuinely want one product with variants, that is a catalogue edit, not a storefront layer.

Install and switch on the app embed

Installing from the App Store puts the app in your admin. It does not yet put anything on your storefront: that takes one more switch, and it is the single most common reason a merchant sees no change.

1. Install the app from the Shopify App Store.
2. In your Shopify admin open Online Store, then Themes, then Customize on your live theme.
3. Open App embeds in the left panel.
4. Switch Rubik Combined Listings on, and save.

The app dashboard carries an app embed status card so you can check this without opening the theme editor. It reads Active, Inactive or Action needed, and it can tell you the awkward case: the embed is on, but on a draft theme rather than the live one.

Create your first product group

A group is one family of products, however many products are in it. Twelve colours of one jumper is one group, not twelve.

1. Open Product groups and choose Create product group.
2. Give it an internal name. Only you see this, so name it the way you would name a folder.
3. Set the option name. This one the shopper sees, above the swatches. It defaults to Colour, and Material, Finish, Size and Style are all common.
4. Choose the products with Select products, which opens Shopify's own product picker.
5. Give each product an option value: Navy, Sand, Oak. This is the swatch label.
6. Give each product a swatch: a colour, or an image, or leave it to the product's own first image.
7. Save, then open one of those products on your storefront.

Display order, when a product is in two groups

A product can belong to several groups: a colour family and a material family, say. Each group carries a display order, and the lower number renders first on the product page. Set it deliberately once and you will not think about it again.

Magic Fill: let the AI name the colours

Typing an option value and picking a hex colour for forty products is the part of this job nobody enjoys. Magic Fill does it from the product images and titles.

Add the products to a group, set the option name, then press Magic fill. It works through the products one at a time, writing the option value and choosing the swatch colour, including a second colour when the product is visibly two tone. A progress bar shows where it is, and you can stop it part way; what it has already filled is kept.

What makes it accurate

It reads the group as a group rather than each product alone. When every title in the group starts with the same words, it strips them, so Merino Crew Neck Navy becomes Navy rather than the whole title. It looks at the image as well as the title, which is how it tells heather grey from charcoal when the titles say neither.

Credits

One product processed is one AI credit. Every plan includes a monthly allowance, the free plan included. Grouping and naming things by hand costs nothing at all, so the allowance is a ceiling on the automation rather than on the app.

Group a whole catalogue at once

Bulk grouping scans your catalogue and proposes the groups it can see, so a few hundred products can be organised in one session instead of one form at a time. You review what it found before anything is created.

Four ways it can find a family

• By title. It looks for products whose titles differ only at the end, or only after a separator. It handles reversed word order too, so Navy Merino Crew and Merino Crew Navy can still land in the same family.
• By tag. If you already tag products, or are willing to, a structured tag names the group, the option and the value outright. This is the most exact of the four, because you are telling it rather than asking it to guess.
• By metafield. Products that share a value in a metafield you already fill in, such as a style code or a parent SKU, are grouped on that value. For most catalogues that already carry a parent code, this is the fastest route.
• By CSV. Upload the groups outright. Worth it when the grouping already exists somewhere else, in a PIM or a supplier feed, and none of the other three can see it.

Which to pick

If your product data has a parent code, use the metafield. If it does not but your titles are consistent, use titles and read the preview carefully. Tags are worth the effort when neither fits, because a mistake is fixed by editing one tag. Reach for CSV when the grouping already exists outside Shopify and you would rather move it than re-derive it.

Designing the swatches

Start from a preset and change what you want. There are eleven presets for product pages and eight for product cards, covering polaroids, circles, rounded squares, pills with images inside, a carousel and the plain dropdown.

Three kinds of swatch

• Image. A picture of the product in a card, with the label and optionally the price under it. Best when the difference is visual and detailed, such as a print or a wood grain.
• Button. A text pill, optionally with a small image inside it. Best for sizes, or for colours whose names carry more meaning than their swatch would.
• Dropdown. The browser's own select. Best when a family is long and the storefront has no room for a row.

Four contexts, set separately

Settings are held independently for the product page on desktop, the product page on mobile, the product card on desktop and the product card on mobile. The component works out which it is in at runtime and applies that set. This matters more than it sounds: a 60px polaroid that reads well on a product page crowds a phone-sized collection card, and the default for cards is a 32px circle for exactly that reason.

Describing a change instead of building it

The visual assistant takes a sentence. Make the swatches round and a little bigger, add a thin border, tighten the gap. It edits the same settings the manual controls write and updates the live preview, so you can take over by hand at any point.

Two options at once

A family that varies in two ways can show two rows: style above, colour below. The shopper picks along each axis rather than reading one long row where both are mixed together. This is worth setting up whenever a group has more than about eight products and a second dimension to it.

Why your theme cannot break them

The swatches render inside a shadow root. Your theme's CSS cannot reach into them and their CSS cannot leak out into your theme. That is why a theme update does not disturb the layout, and it is also why a custom CSS field exists: ordinary theme CSS has no way in.

Swatches on collection pages and product cards

Product card swatches are the half of the app most themes cannot do at all. A theme that shows swatches on a card is showing that one product's variants; it has no way to know that four other products belong with it.

Card swatches render on collection pages, search results and any product list on the home page. Hovering a swatch swaps the card image so a shopper can see the colour in place; clicking takes them to that product's own page, because it is a real, separate product.

Things worth setting deliberately

• One row or many. Cards default to a single row with the rest counted in an overflow chip, because a card that grows taller than its neighbours breaks the grid.
• Labels and prices. Both off by default on cards. A card already carries a price, and a second one next to it reads as an error.
• Sold out products. Hide them, strike them through, or leave them in. The setting is separate from the product page, and hiding on cards while showing on the product page is a common and sensible combination.

Subcategories, sold out rules and ordering

Subcategories split one group into labelled sections. A family that varies by both material and colour reads as two shorter rows rather than one row of twenty, and the shopper can see the structure of the choice rather than just its size.

Sold out behaviour is set per context. A product with no stock can be hidden from the row, shown with a struck through swatch, or left exactly as it is. Striking through tends to convert better than hiding on a product page, because it tells the shopper the colour exists; hiding tends to be better on collection cards, where there is no room to explain.

Sorting decides the order of the swatches themselves. Beyond the order you drag them into, the app can push new products to the start, sort alphabetically, show the selected product first, or lead with the products that still have the most sizes available. Out of stock products can be pushed to the end rather than hidden, which keeps the row honest without burying it.

Display order decides two things: which group leads when a product is in several, and the order of the products inside a group. Swatch order is the order of the products in the group, so drag them into the order you want a shopper to read.

Selling in more than one language

Option names and option values are text a shopper reads, so on a multi language storefront they have to be translated. Doing that one swatch at a time is not a plan, so the app exports them as a CSV and imports the translated file back.

The export carries every group's option name and every product's option value. Translate the column, import it, and the storefront serves the right language from the same groups. Nothing about the grouping itself is duplicated per language.

Themes, page builders and custom selectors

To put swatches on a product card, the app has to know which part of the page is the card, which part is the title, which is the price and which is the image. That map is per theme, and the app carries it for 358 of them: 283 official Shopify themes, 68 third-party themes and 7 page builders.

How your theme is detected

The app reads the theme store id Shopify exposes on the storefront. When a theme is customised past recognition, or is not from the theme store at all, you can name it yourself in the app embed management screen. For page builder pages this is worth doing deliberately, because a builder page is structured by the builder rather than by the theme underneath.

When your theme is not on the list

Many unlisted themes work anyway, on generic selectors. When they do not, the custom selectors feature lets you point at the elements yourself, and support will map a theme for you if you send the store URL. A mapped theme benefits everyone on it, so this is worth asking for rather than working around.

Pages that load after the page

Infinite scroll, quick view modals and AJAX filtering all add product cards after the page has loaded. The app watches for them and injects swatches into the new cards. Some themes go further and rebuild the product page when a selection changes; that is watched for too, and the component re-injects itself.

When something is not showing

Nothing at all on the storefront

The app embed is off, or on on a different theme. Check the status card on the dashboard first. This accounts for most of these tickets.

Swatches on product pages but not on collection cards

Either card swatches are switched off, or your theme's card is not the one the app expects. Try naming your theme by hand in the app embed screen, and if that does not do it, send support your collection page URL.

A product is missing from its group

Draft and archived products are excluded on purpose, and a product that was drafted will reappear when it is active again. Otherwise check that the product actually carries an option value: a product with no value has nothing to render as a swatch.

The change I just made is not live

Give it a minute and reload with the theme editor closed. A preview session can serve an older copy of the storefront data than a real visit does.

Another app is fighting with this one

An app that also rewrites the variant picker or the product card can collide. Tell support which app it is; most of these end with a setting on one side rather than a choice between the two.

Plans, limits and what counts

Plans differ in two numbers only: how many groups you can have, and how many AI credits you get each month. Every feature is on every plan, the free one included. There is no feature behind an upgrade.

A group is a family, not a product. A group of twelve colours counts as one against your limit. This is why the free plan's five groups covers more of a catalogue than it first sounds like.

An AI credit is one product processed by Magic Fill or the visual assistant. Building groups by hand never spends one.

Annual billing is two months off. The listing rounds it to 17 per cent.

If you go over your group limit, existing groups keep working. You are asked to upgrade before adding more.

Seeing what shoppers clicked

The app records swatch clicks and reports on them, which turns the swatch row from a convenience into a source of merchandising data you did not have before.

What it reports

• Clicks, split by surface. Product page clicks and product card clicks are counted separately, because they mean different things. A card click is a shopper browsing; a product page click is a shopper deciding.
• Most clicked products, and top groups. Which individual products pull attention, and which families do.
• Mobile against desktop. The split is usually more lopsided than merchants expect, and it is the argument for setting the mobile swatch size deliberately rather than inheriting it.
• Clicks by swatch position. How far along the row a shopper is willing to look, which is the case for ordering the row rather than leaving it alphabetical.

Sold out demand

The report that earns its place: clicks on swatches for products that were out of stock at the moment of the click, ranked by product. It is demand your storefront measured rather than demand you estimated, and nothing else in Shopify produces it. Read it as a restock list.

For developers

A click event you can listen to

Every swatch click fires a custom event on window, carrying the group and the product involved. Analytics, recommendation widgets and anything else that wants to know which colour a shopper is browsing can listen for it without touching our code.

A public JavaScript API

The component exposes methods for re-injecting itself and for reading current state, which is what you want on a heavily customised theme that rebuilds its own DOM.

Shadow DOM

Swatches live in a shadow root. Your stylesheet cannot select into it, which is deliberate. Style them through the app's settings or its custom CSS field, both of which are injected inside the root.

Shopify Sidekick

Sidekick, Shopify's own assistant in the admin, can create and edit product groups here. For a merchant already asking Sidekick to do things, it is the shortest path from an idea to a group.

An MCP server

The app ships an MCP server, so an AI assistant can list, create and edit product groups and settings on your shop with a token you issue and can revoke. It is available on every plan, including the free one.

Nothing on the storefront calls our servers

Product page swatches come from data already rendered into the page. That is a deliberate architectural rule: a slow or unreachable app server is an admin incident, never a storefront one.

Plans at a glance

The pricing page explains what counts as a group.

Still stuck

Support is live chat and email, answered by the people who build the app, on every plan including the free one. Open the app in your Shopify admin and use the chat there: it arrives with your shop already identified, which saves the first three messages.

If your theme is the problem, send the URL of a collection page. Most theme issues are a mapping we can add for everyone rather than a setting for you.

• The questions page, searchable
• Video walkthroughs
• Whether your theme is mapped