↑↓ selectEnter openEsc close

    1. Elbuz

    How to group color and size variants into a product family

    22 min readUpdated

    Elbuz links separate catalog products — colors and sizes of one model — into a family. Shoppers then switch variants with color swatches and size buttons right on the product page, without returning to the catalog.

    When you need this:

    • A T-shirt in several colors and sizes — the product page gets color swatches and size buttons.
    • Manufacturer color names: Graphite, Sierra Blue — the color reference picks the shade.
    • A variant sold out — an in-stock product becomes the group's main one.
    • A group needs renaming or breaking up — bulk-change one column in the product grid.

    Where to start: mark color and size as variant attributes under “Attributes”.

    What product families can do

    How products are linked into a family

    A family is not one product with variants inside it. It's several standalone catalog products linked by a shared family name. It's made of three things:

    1. Separate catalog products — each combination of attributes is its own product card. “T-shirt Classic M white” and “T-shirt Classic M black” are two products.
    2. The same family name on all these products — this is what links them.
    3. Variant attributes — the attributes shoppers switch by: color, size, storage, volume.
    Four steps and two conditions without which the family won't come together. The yellow diamond is a decision point: at each one, the family can silently fail to appear
    NoYesNoYesStep 1. Color or size attribute —the “variant” flagStep 2. The same “Family name”on all products in the groupName matchescharacter for character?Product stays outside the family.An extra space or different case —already a different familyStep 3. Color reference:a color code for each valueStep 4. “Product Families” checkboxin the tunnel settingsfor an OpenCart 3 websiteCheckbox on?Family datadoesn't go to the website at allOn the website: color swatchesand size buttons
    • Action or result
    • Decision: the path depends on the answer

    The family name must match character for character. The program ignores letter case and trailing spaces. But an extra space at the start or in the middle, a different letter or a typo, and the product stays outside the family.

    There is no “close enough” matching, so copy the name from the first product instead of typing it each time.

    When a family has more than one product, the grid shows a layers icon with the number of products in the family next to the stock status; its tooltip reads “Products in the family (same model/family name)”. After you change the family name in the grid — in a cell or with “Set value in bulk” — the counter is recalculated right away for all products of the old and the new family.

    If family names got into the catalog some other way, the icon appears after the catalog is reindexed.

    For option products (variants inside a main product), you don't need to fill in the family name: the program sets it from the main product's data and overwrites it on reindex. Families are a different, “flat” way to link products, and they need separate product cards.

    Step 1. Mark variant attributes

    In the “Attributes” window, find the attributes your products differ by and turn on “Use to create variable products” for them.

    Typical variant attributes: color, size, built-in storage, volume, weight. You set this once per attribute, and it applies to the whole catalog — every product with this attribute filled in can use it for switching.

    How many attributes to use. One (only color or only size) is the simplest and most reliable: all buttons are always active. Two suits electronics and clothing best, but the matrix rule applies. Three or more — the products you need multiply: 3 colors × 4 sizes × 2 materials = 24 cards.

    Why some buttons on the website are inactive

    A button is active only when there's a product with the matching combination of attributes. Say a family has two variant attributes — storage and color:

    Products in the familyWhat the shopper sees on the “128 GB, blue” product
    128 blue, 128 green, 256 blue, 256 greenall buttons are active: there's a product for each
    128 blue, 256 green“256 GB” is inactive (no “256 + blue” product), “green” is inactive (no “128 + green”)

    For all buttons to be active, you need a separate product for each combination: 3 colors × 4 storage options = 12 products. If some combinations are missing, that's fine: shoppers will see that the variant doesn't exist.

    With one variant attribute, the matrix rule doesn't apply: all buttons are always active.

    Step 2. Fill in the family name

    For each product in the group, fill in the “Variant family name” column with the same value.

    Use the base name, without the variant attributes: “iPhone 15 Pro”, not “iPhone 15 Pro 256GB Blue”. Shoppers don't see it — it's an internal group name for you.

    If a product line has several models, those are several different families: “iPhone 15”, “iPhone 15 Pro”, “iPhone 15 Pro Max”.

    Product in the catalogFamily name
    iPhone 13 Pro Max 128GB GraphiteiPhone 13 Pro Max
    iPhone 13 Pro Max 256GB Alpine GreeniPhone 13 Pro Max
    iPhone 13 128GB BlueiPhone 13

    The first two products end up in one family, the third in another. Each product must also have its variant attribute values filled in: a product with no color won't get a color button, even if it's in the family.

    Step 3. Show a color swatch instead of a word

    To show a swatch of the matching color on the website instead of the word “black” or “Blue”, you need hex color codes. They're stored in the “Color Reference” — the brush button in the “Attributes” window.

    1. Select the color attribute in the list.
    2. Click “Fill values from products” — the program collects all unique values of this attribute from the catalog and tries to work out the color from the name.
    3. Check the result. Where the color wasn't detected, click the “Color” cell and pick a shade from the palette.
    4. For two-color variants, fill in “Second color (gradient)” — the website shows a two-color swatch.

    Auto-detection understands names in Ukrainian, Russian and English and knows marketing names: Graphite, Midnight, Starlight, Sierra Blue, Alpine Green, Product Red, Space Gray.

    It splits compound values into parts and fills both columns with the first two colors it finds. Separators: slash, plus, comma, or the conjunctions “і”, “и”, “and”: “black/red”, “white + gray”, “black and gold”.

    What “Fill values from products” does with each row. The middle decision point explains why your manual colors survive: the button skips a row that already has a color
    NoYesYesNoNoneOneTwo or more“Fill values from products”Attribute selectedin the list?Hint “Select an attribute first”,the reference doesn't changeAttribute values from productsnot yet in the reference are addedRow alreadyhas a “Color”?Row doesn't changeValue is split into partsby “/”, “+”, commaand the conjunctions “і”, “и”, “and”.If it has the word “gradient”, onlythe text after it is usedHow many partsare recognized by name?Color stays “not set” —pick it in the palette“Color” is filled inFirst two go to “Color”and “Second color (gradient)”
    • Action or result
    • Decision: the path depends on the answer

    Running “Fill values from products” again doesn't overwrite colors you set by hand: only empty ones are filled. So you can click the button every time new color names appear in the catalog.

    A color is found by the exact attribute value. Letter case doesn't matter: “Black” and “black” are one reference row. But “black”, “matte black” and “blk.” are three different rows, and each needs its own hex.

    Before filling in the reference, bring the spelling to one form — checking attribute values helps with this.

    The button works only with the attribute selected in the list and takes all non-empty values across the whole catalog in one go, with no limit on the number. It only adds rows: a value that no longer appears in any product stays in the reference until you delete it yourself.

    The reference has only two fields per value — “Color” and “Second color (gradient)”, both in HEX. So a selector swatch is either one-color or two-color, and shoppers see a texture or print on the photo of the variant product itself.

    How to clean up the color reference

    You can delete rows you don't need. Only colors of values that products in the family currently have go to the website, so a row that isn't in any product has no effect.

    • “Clear color” clears the hex in the selected row; the row itself stays.
    • “Delete” removes the selected row: the program first asks “Delete the color “…” from the reference?” and deletes the row only after you confirm.
    • “Clear all” deletes all rows of the selected attribute after asking “Are you sure?”.

    On the reference toolbar these buttons are icons without labels; the name appears when you hover over the icon.

    Color Reference window with the Color attribute selected, the toolbar of five icon buttons and the table of values with colors
    1Fill values from products
    2Clear color
    3Delete
    4Clear all
    5Color swatch
    1. Fill values from products — writes every unique attribute value from the catalog into the reference.
    2. Clear color — resets the color of the selected value.
    3. Delete — removes the selected value from the reference.
    4. Clear all — removes all values of the attribute from the reference.
    5. Color swatch — the color assigned to a value; a second color makes a gradient.

    The reference has no undo button. If you delete or clear the color of a value that products have, it goes to the website without a swatch on the next export.

    If an attribute has no values with a color left and its type isn't “Color”, that attribute's whole selector goes to the website as text buttons.

    Running “Fill values from products” again brings back deleted rows for values that products have. It again tries to detect the color from the name for all rows with an empty hex — including ones where you cleared the color on purpose. A color you picked in the palette by hand isn't touched by a repeat run.

    When you delete the attribute itself, its rows in the color reference are deleted along with it.

    Step 4. Export families to your website

    In the tunnel template card, under “What to export”, turn on the “Product Families” checkbox and run the export. Without it, family data won't go to the website — family names in the catalog do nothing on their own.

    The checkbox exists only in the tunnel for an OpenCart 3 website: for other it's not in the settings.

    The export includes only products that have export turned on and a family name filled in. A product excluded from export disappears from the selector, even if it has a family name.

    After the export, the website shows color swatches (including two-color ones), text buttons for storage and size, and links between products of the same family.

    Which product becomes the family's main product

    For structured data and links, the group needs an “anchor” — the main product. The program picks it automatically, on every export, and only from the family's products included in that export (taking the template's filters into account — categories, store). Two rules, in order:

    1. first, products that are in stock;
    2. among them, the most expensive.

    If none are in stock, the most expensive product in the family becomes the main one.

    The rule is dynamic on purpose and ignores the main product assigned in the catalog: otherwise the group could send shoppers to an “Out of stock” page. The choice may change on the next export — that's normal.

    Pre-export checklist

    • every variant is a separate product card;
    • the variant flag is on for the attributes you need;
    • the family name is identical character for character;
    • variant attribute values are filled in for every product;
    • the color reference has a hex for every color value;
    • products are active, in stock and have export turned on;
    • with two attributes, the combination matrix is checked.

    What happens if the export is interrupted

    Families go to the website in a separate export step, and this step doesn't add to what's already on the website — it rebuilds everything from scratch:

    1. the program sends three lists to the website: variant attributes, families with their main products, family products with colors;
    2. if all three lists arrived, the family tables on the website are fully cleared;
    3. the tables are filled again from these lists.

    These are separate commands in a row, with no shared rollback.

    Who sends what to whom during the “Export Product Families” step. Look at the last two arrows: an interruption between clearing and filling is what leaves the website without some of its selectors. The program rebuilds the family tables on the website side for OpenCart 3 websites
    OpenCart 3 websiteElbuzalt[Website returned an error]website catalog products are updatedfamily tables on the website aren't touched —families from the previous export remainseparate commands in a row with no shared rollback —an interruption after clearing leaves the website without some selectorsalt[At least one list failed to upload][All three lists arrived]create empty staging tables for familiesexport stops —the website keeps the previous familieslist 1 — variant attributes,type “color” or “text”list 2 — families and the main product of eachlist 3 — family products,attribute values and colorsclear the family tablesfill them from the three lists
    • Request or action
    • Reply
    • alt — one of the options, depending on the condition
    • Note
    • If the export stopped before it reached clearing the family tables, the website keeps the families from the previous successful export.
    • If even one of the three lists didn't reach the website, the program doesn't touch the family tables on the website: clearing and filling are skipped, and the families from the previous successful export remain. The list transfer error shows in the export log.
    • If the interruption happened after clearing, selectors on the website can disappear partly or completely — until the next successful export.
    • Running it again is safe: it clears the family tables again and rebuilds them from current catalog data, so families aren't duplicated and nothing is left over from the interrupted run.

    In Elbuz itself, the export doesn't change the family name on products, so after an interruption no product in the catalog is left without its family.

    How to fix a family you already built

    To rename a family or break it up, change the “Variant family name” column for the group's products: check them and use “Set value in bulk” or “Find and replace” on this column.

    If you leave the field empty in “Set value in bulk”, the program asks “Do you want to clear the values in the selected field?” and, after you confirm, erases the family name — the products no longer belong to any family.

    • If you change the name the same way for all products in the group, the family simply gets a new name. Shoppers don't see this name, so on the website only the group membership changes, if it changed.
    • If you change the name for only some of the products, the group splits in two: products with the new name form a separate family, the rest stay in the old one.
    • If you clear the name, the product disappears from the selectors on the next export, but stays on the website as a regular product card.

    The change reaches the website on the next export with the “Product Families” checkbox on: it rebuilds all families on the website from what's currently stored in the catalog.

    Changing the family name of main products with option products, or of the options themselves, is pointless: on reindex the program writes it again from the main product's name, SKUs and model.

    After “Set value in bulk”, the family product counter is recalculated for all products of the old and the new family. “Find and replace” recalculates it only for the checked products.

    After using it, recalculate the counter for the whole catalog: the “System functions” window → the “Reindex records” section → “Base catalog products”.

    What happens if a bulk change is interrupted, and how to undo it: what happens after you run a bulk change.

    Scenarios

    Clothing: color as swatches, size as buttons

    Task: a T-shirt in several colors and sizes; the shopper needs to switch between them on the product page.

    What to turn on:

    • for the color and size attributes — “Use to create variable products”;
    • for all T-shirts of the model — the same “Variant family name”;
    • in the “Color Reference” for the color attribute — “Fill values from products”;
    • in the tunnel settings — “Product Families”.

    Result: an attribute that has at least one value with a color in the reference goes to the website as a color selector. Size has no colors in the reference, so it goes as text buttons.

    What you won't get: a swatch for a value with an empty “Color”, or a place in the selector for a T-shirt with export turned off.

    Smartphones with marketing color names

    Task: colors in the catalog are written the way the manufacturer writes them — Graphite, Sierra Blue, Midnight — and some are two-color.

    What to turn on: first, “Use to create variable products” on the color attribute — the reference list shows only attributes with this flag. Then, in the “Color Reference”, select the color attribute, click “Fill values from products” and review the rows with “not set”.

    Result: these names get a color automatically. Values with “/”, “+”, a comma, or the conjunction “і” or “and” fill both color columns if both parts are recognized. Colors you already set in the palette aren't overwritten when you click again.

    The group shouldn't point to a product that's out of stock

    Task: make sure the family's anchor on the website is always a product shoppers can buy.

    What to turn on: there's no separate setting — “Product Families” in the tunnel and up-to-date stock in the catalog are enough.

    Result: on every export, an in-stock product becomes the main one under the main product rule. You can't pin the main product manually.

    What to do when a family doesn't work on the website

    What you seeWhyWhat to do
    The product didn't get into the familythe family name differs by a space at the start or in the middle, or by a typocopy the name from another product in the group
    The product is in the family, but has no buttonthe variant attribute value isn't filled infill in the attribute on the product card
    Text or an empty spot instead of a swatchthe color reference has no hex for this valueopen the reference and set the color
    Not all variants have colorscolor values are spelled differentlybring the spelling to one form, then fill in the reference
    Some buttons are inactivethere's no product with this combination of attributescreate the missing combinations or keep one variant attribute
    Families aren't exportedthe “Product Families” checkbox in the tunnel is off (it exists only for an OpenCart 3 website)turn it on in the export settings
    Selectors didn't appear, although attributes are filled in“Use to create variable products” isn't turned onturn it on for the attribute
    The product disappeared from the selector on the websiteit's inactive, out of stock, or excluded from exportcheck these three settings on the product card
    There's no icon with the family product count in the gridfamily names got into the catalog other than through the grid, and the counter hasn't been recalculated yetwait for the catalog to be reindexed
    The family's main product changed by itselfthe anchor is chosen every time: in-stock first, then the most expensivethis is by design

    FAQ

    Will the program create products for all combinations by itself?

    No. You create each color and size combination as a separate product card; the family only links existing products. (more)

    Can I add a product to several families?

    No. A product has one family name and belongs to exactly one group.

    How many products can one family have?

    There's no limit. But the more variants, the more buttons shoppers see: the practical limit for comfortable viewing is about twenty to thirty products per group.

    Do I have to fill in the color reference?

    Only if you want color swatches. Without hex codes, the color selector shows text buttons — just like storage or size.

    I assigned a main product — why is the anchor on the website different?

    The family's main product is chosen automatically on every export: in-stock products first, and among them the most expensive. The assignment in the catalog doesn't affect this choice. (more)

    What happens if I remove a product from a family?

    After the next export, the family updates by itself: the removed product disappears from the selectors on the website.

    Can I use families for only part of the catalog?

    Yes. A family is formed only from products that have a family name filled in. The rest of the catalog is exported as usual.

    Can I upload a fabric texture image to the color reference?

    No. The “Color Reference” has only the “Color” and “Second color (gradient)” fields, in HEX. Shoppers see a texture or print on the photo of the variant product itself. (more)

    Where to find it and who has access

    Menu
    Directories → Base product catalog → Products, the “Variant family name” column
    Variant attributes
    Directories → Base product catalog → Attributes
    Colors
    the “Attributes” window → the “Color Reference” button (brush)
    Export
    tunnel settings, the “Product Families” checkbox — OpenCart 3 only
    Access rights
    the “Products” and “Attributes” windows; for exporting — “Data export”

    Next to the “Variant family name” column, the grid has “Variant count” — how many products are in the group.

    Products grid with the Variant family name column filtered by a word
    1Variant family name column header
    2Family name in a product row
    1. The Variant family name column header, with the filter field below it.
    2. A filled family name: products with the same name belong to one family.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free