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
- Link separate product cards into a group — by the same family name; each variant keeps its own price, photos and stock.
- Switch variants by attributes — color, size, storage, volume become buttons on the website.
- Show a color as a swatch — the color reference works out the shade from the name, including two-color variants.
- Point the group to an in-stock product — the main product is chosen on every export.
- Rebuild families on the website — a repeat export builds them from scratch, with no duplicates.
- Rename or break up a group — with a bulk change to one column.
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:
- 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.
- The same family name on all these products — this is what links them.
- Variant attributes — the attributes shoppers switch by: color, size, storage, volume.
- 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 family | What the shopper sees on the “128 GB, blue” product |
|---|---|
| 128 blue, 128 green, 256 blue, 256 green | all 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 catalog | Family name |
|---|---|
| iPhone 13 Pro Max 128GB Graphite | iPhone 13 Pro Max |
| iPhone 13 Pro Max 256GB Alpine Green | iPhone 13 Pro Max |
| iPhone 13 128GB Blue | iPhone 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.
- Select the color attribute in the list.
- 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.
- Check the result. Where the color wasn't detected, click the “Color” cell and pick a shade from the palette.
- 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”.
- 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.
1
Fill values from products2
Clear color3
Delete4
Clear all5
Color swatch- Fill values from products — writes every unique attribute value from the catalog into the reference.
- Clear color — resets the color of the selected value.
- Delete — removes the selected value from the reference.
- Clear all — removes all values of the attribute from the reference.
- 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:
- first, products that are in stock;
- 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:
- the program sends three lists to the website: variant attributes, families with their main products, family products with colors;
- if all three lists arrived, the family tables on the website are fully cleared;
- the tables are filled again from these lists.
These are separate commands in a row, with no shared rollback.
- 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 see | Why | What to do |
|---|---|---|
| The product didn't get into the family | the family name differs by a space at the start or in the middle, or by a typo | copy the name from another product in the group |
| The product is in the family, but has no button | the variant attribute value isn't filled in | fill in the attribute on the product card |
| Text or an empty spot instead of a swatch | the color reference has no hex for this value | open the reference and set the color |
| Not all variants have colors | color values are spelled differently | bring the spelling to one form, then fill in the reference |
| Some buttons are inactive | there's no product with this combination of attributes | create the missing combinations or keep one variant attribute |
| Families aren't exported | the “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 on | turn it on for the attribute |
| The product disappeared from the selector on the website | it's inactive, out of stock, or excluded from export | check these three settings on the product card |
| There's no icon with the family product count in the grid | family names got into the catalog other than through the grid, and the counter hasn't been recalculated yet | wait for the catalog to be reindexed |
| The family's main product changed by itself | the anchor is chosen every time: in-stock first, then the most expensive | this 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.
1
Variant family name column header2
Family name in a product row- The Variant family name column header, with the filter field below it.
- A filled family name: products with the same name belong to one family.
Related topics
- If the variant flag doesn't show for an attribute — the attribute directory.
- If a color is written differently across products — How to clean up attribute values.
- If a supplier's variants come in as options of one product — option products.
- If you need to export families to your website for the first time — exporting to your website through the tunnel.
