Variants & combinations

Variants let one product cover multiple options — colors, sizes, capacities, brands, models. Customers see a clean picker on the product page; you keep one product record instead of a duplicate per colour. This page is the deepest reference in the Selling section because variants quietly drive most of the dashboard work for fashion, electronics and digital products.

Video

The vocabulary

Concept	What it is
Variant group	One dimension of choice — Color, Size, Storage, Brand. A product can have several.
Variant option	One value inside a group — Red, XL, 64GB, Apple.
Combination	A specific cross-pair — Red + XL. Used when each pair has its own SKU and stock.
Price pill	The small price label shown on the option, computed as base price + the option's price adjustment.

A product with 3 colours × 4 sizes has up to 12 combinations. You don't have to use combinations — most products track stock at the option level or at the product level instead (see §Stock modes).

The three variant types

Every option carries a type that controls how the storefront renders it:

Type	What customers see	Use when
Color	A filled circle in the option's hex colour	The colour is the whole story (Red, Blue, Black).
Text	A text pill (S, M, L, XL)	Sizes, materials, capacities, generic options.
Image-text	A small thumbnail with the option name underneath	Brand logos, model thumbs, anywhere a tiny image clarifies the text.

The image-text type is newer than the other two. Use it whenever you have more than ~5 text options — the thumbnail prevents customers from misreading similar names ("iPhone 14 Pro" vs "iPhone 14 Pro Max"). When the option is bound to a product image, clicking it scrolls the product gallery to that image.

Creating a variant group

Go to Dashboard → Products at /dashboard/products, then either:

• Click Create product at /dashboard/products/create, or
• Open an existing product to edit at /dashboard/products/:id/edit.

Scroll to the Variants card, then:

1. Click Add variant group.
2. Type a group name (e.g. Color, Size, Brand).
3. Pick the type (Color, Text, or Image-text).
4. Click Add option for each value.

You can drag groups to reorder them — the storefront renders groups top-to-bottom in this order.

Adding options

Each option carries:

Field	What it does
Name	The label customers see (Red, Small, Apple).
Color code	Hex value, only for color type — drives the swatch.
Linked image	For image-text (and optional for color). Pick one of the product images already uploaded above. The link uses a stable image ID, not the URL — see §Click-to-gallery.
Show as card	Toggles a larger card layout with image + price pill (vs. a small swatch/pill).
Price adjustment	A delta on top of the base price. Can be positive (+200), zero, or negative.
Stock	Stock for that option (used when you don't track combination-level stock).

The price pill — it's a delta, not the absolute price

This is the most common mistake when setting up variants:

If your base price is 2 500 DZD and the XL costs 2 700 DZD, the price adjustment for XL is +200, not 2700.

The storefront renders the final price (base + adjustment) on the option card and recomputes the cart total when the customer picks an option.

The "Show as card" toggle

Set Show as card when you want the option to render as a larger tile with the linked image and the final-price pill — useful for fashion, jewellery, and brand selectors. Leave it off for compact swatches and text pills (sizes don't need to be cards).

Required vs. optional groups

Each group can be marked required. When a group is required, the customer can't add the product to cart without picking one option from it. This is enforced server-side, so a stale browser tab can't slip an empty selection through. Always mark Color and Size as required; mark optional engraving / personalisation groups as not required.

Click → gallery scroll

When an option is bound to a product image, clicking it on the storefront scrolls the product gallery to that image. The link uses the image's internal ID, so reordering or replacing pictures later doesn't break the binding.

This is why the dashboard lets you pick a product image as the option's linked image — picking by ID instead of by file means the "main image won't stick after save" bug no longer exists.

Stock modes

The platform supports three ways to track stock. They follow this priority on the storefront:

1. Combination stock — a separate stock count for each (Color × Size) pair.
2. Option stock — one count per option (a single "Red" pool shared across sizes).
3. Product stock — a single number on the product itself.

If you don't enable combinations, stock is read from the option (when set) and falls back to the product otherwise.

When to enable combination stock

Toggle Track combination stock when:

• Different (Color × Size) pairs really do have different stock (a Red XL pile that runs out before the Red M pile).
• You need a per-pair SKU for inventory or accounting.

Otherwise leave it off. Combinations explode quickly: 4 colours × 5 sizes = 20 SKUs to manage. 4 × 5 × 3 storage tiers = 60. The dashboard handles up to ~1000 combinations comfortably; beyond that contact support.

When you enable combination stock, the Combination matrix card appears below the variant groups. Click Generate combinations to build the grid, then type a stock count for each row.

Reordering images and the variant gallery

The product image grid (above the variant section) is where merchants spend most of their time:

• Drag-and-drop to reorder on desktop.
• Long-press for ~250 ms on mobile to enter reorder mode (with a small haptic tick).
• The chevron < and > buttons on each image card nudge it one slot left/right — handy for slow drag on mobile or precise placement.
• The primary image is locked to position 1 — reordering the rest doesn't move it.

The order is persisted via an image_order[] array when you save the product, and is what the storefront uses for the gallery and for the option-to-image binding.

Cascading Variants (addon)

Some catalogs have dependent options — Brand → Model. Selecting Apple should only show iPhones, not Samsung Galaxies. Install the Cascading Variants addon to enable parent-child groups:

• Parent option chosen → child group is revealed.
• Other options for the parent are hidden until the customer changes their pick.
• Compatible with color, text and image-text types, plus combination stock.

Activate it from /dashboard/addons — requires the Pro plan or higher.

Offer Variant Popup (addon)

When you sell multi-quantity offers ("Buy 3, get 1 free"), the customer needs to pick variants for each piece, not just once. The default in-page selector gets crowded — the Offer Variant Popup addon replaces it with a modal:

• Beautiful responsive popup, one piece at a time.
• Shows variant images, colours and names.
• Optional auto-advance to the next piece after a selection.
• Compatible with combination stock.

Activate it from /dashboard/addons — available on all plans, including Free.

Digital Product Variants (Digital theme only)

If your store uses the Digital theme, the Digital Product Variants addon transforms the variant selector into a sleek 2-step accordion:

• Each option shows the final price (base + adjustment) directly on the card.
• Single-selection across all groups (no multi-pick).
• Smooth keyboard-accessible animation matching the Digital theme.
• Zero per-product setup — activate and it applies everywhere.

Requires the Pro plan or higher and the Digital theme.

Tips

• Set the price pill as a delta, not the absolute price. Most setup mistakes come from typing 2700 instead of +200.
• Use image-text once you pass ~5 options in a group. Thumbnails kill misreads on similar names.
• Don't enable combination stock unless you really need it. 4 × 5 = 20 SKUs is a lot to keep in sync.
• Cards are great for fashion and brands, overkill for sizes.
• Mark Color and Size as required — empty selections produce empty order_item_variants rows that break delivery labels.
• Lock your primary image before reordering. Customers in ads land on the primary image; don't accidentally swap it.
• Test the popup on a phone. Multi-quantity offers should always be checked in mobile width — the popup is more critical than the inline selector.

What's next

• Products — the page that hosts variants.
• Cascading Variants addon
• Offer Variant Popup addon
• Digital Product Variants addon