Variant families

A variant family (formerly called variant grouping) is an ordered hierarchy of attributes that arranges products into a tree — for example, MODEL → COLOR → CAPACITY. Configure it on the Variant families tab. The tree itself appears later in the grouped view of the product list.

What the screen looks like

The list of families is on the left, with each family's levels shown beneath its name, for example, MODEL › COLOR. Search (including by name), the Active / Inactive / All switch, and pagination work on the server. The editor for the selected family is on the right: its name in the heading, an Active switch, a trash icon, and a sentence below the heading, for example, The Clothing family groups products by Model › Color and is the default in Demo Catalog. Click an underlined part to open the relevant tab.

Editor tabs:

• Hierarchy — levels in order. The ↑ ↓ arrows change their order, ✕ removes a level, and Add level… adds another. Click an attribute name at a level to open that attribute's editor.
• Catalogs — catalogs where the family is used: Default and Active. Each catalog has one default family; selecting this one clears the marker from the previous one.
• Translations — the name and description in every company language. Translate missing (AI) fills languages without a name; click Save to keep the translations.
• Advanced — Code (unique within the company), Position, Icon.

Click Save to save everything. A direct link to a family looks like ?tab=variant-groupings&grouping=<id>; the family name link in the heading of a key attribute's editor opens it this way.

Step by step

First, mark attributes as grouping keys

1. Go to Catalog → Attributes, on the Attributes and groups tab.
2. Click the attribute you want to use in the tree; its editor opens beside the list.
3. On the Advanced tab, find Population and choose once per product and groups products into a family.
4. Click Save.

Repeat for every attribute you want in the hierarchy. Otherwise it will not appear in the selection list.

Then, build the family

1. On the same screen, open the Variant families tab and click + above the list.
2. The editor opens on Advanced. Enter the Code and the name in the heading.
3. On Hierarchy, use Add level… to choose an attribute for the first level, then choose attributes for the next levels. Use the arrows to adjust their order.
4. On Catalogs, add catalogs and select Default wherever this family should group variants.
5. Click Save. An empty hierarchy cannot be saved; a message will appear by the Hierarchy tab.

Finally, check the tree on the product list

1. Open the product list and select a catalog. Without a catalog, the view switch is not shown at all.
2. Click the view button (Flat) and choose Group variants.
3. In Select grouping..., choose the family you created. The products will be arranged in a tree.

An attribute must be a grouping key

You can add only attributes marked as a grouping key to the hierarchy. The selection list shows only those attributes, and an attempt to bypass this elsewhere fails validation.

If the attribute you need is missing from the list, return to its definition and set Population to once per product and groups products into a family, as described in the first procedure above.

Two hierarchy rules

• The same attribute can appear in a family only once.
• Each hierarchy level can contain only one attribute.

Level 1 is at the top. A hierarchy must contain at least one attribute and cannot have gaps: every declared level must have an assigned attribute.

A family code must be unique within the company.

A product without a value does not disappear

If a product has no value for an attribute at one of the levels, it remains in the tree, under a separate “missing” node at that level. This is deliberate: incomplete data should be visible, not silently omitted. That node is usually the fastest way to find products that need their data filled in.

Caution when editing an existing hierarchy

The check that an attribute must be a grouping key works reliably when adding a new level. When editing an existing row, the same check may not run if the change takes a different path from the form. In practice, instead of replacing the attribute at an existing level, it is safer to remove that level and add it again.