# Group Products as Variants for PrestaShop: Module Documentation (dfproductlinker)

> The DF ProductLinker module (dfproductlinker) links separate product pages so they show as one item with a color, size or any other attribute selector. Each variant stays a full product…

- Page: <https://www.datafirefly.com/en/documentation/dfproductlinker/>
- Language: en
- Last updated: 2026-09-23
- Other languages: [fr](https://www.datafirefly.com/documentation/dfproductlinker/index.md), [es](https://www.datafirefly.com/es/documentation/dfproductlinker/index.md), [de](https://www.datafirefly.com/de/documentation/dfproductlinker/index.md), [it](https://www.datafirefly.com/it/documentation/dfproductlinker/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfproductlinker/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfproductlinker/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfproductlinker/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

The **DF ProductLinker** module (dfproductlinker) links separate product pages so they show as one item with a color, size or any other attribute selector. Each variant stays a full product with its own URL. It is the reverse of [DF ProductSplitter](https://www.datafirefly.com/en/product/separer-declinaisons-en-produits-prestashop/), which splits a product with combinations into separate products.

## Installation

1. Download the ZIP from your DataFirefly customer account.
2. In the back office, go to _Modules > Module Manager > Upload a module_ and send the ZIP.
3. On installation, the module creates its tables and the _Catalog > Linked variants_ tab.
4. Open the module configuration to check the selector position.

The module runs on PrestaShop 8.0 to 9.x with the same ZIP, in multistore and multilingual setups. Its strings ship in French, English, Spanish, German, Italian, Dutch, Polish and Portuguese.

On update, the module clears the Smarty cache. If your shop is set to _Never recompile template files_ and the display does not change, clear the cache from _Advanced Parameters > Performance_.

## How it works: groups and axes

A **group** brings several products together. An **axis** is a native PrestaShop attribute group, such as Color or Size: values, hex colors, textures and translations entered in _Catalog > Attributes & Features_ are reused as they are. Each product of the group gets a value on each axis.

A product can belong to one group only. The products themselves are not modified: groups are stored in the module's tables.

## Creating a group

Go to _Catalog > Linked variants_ then _Add a group_.

1. Enter the **group name**. It is used internally and as a fallback name in structured data.
2. Under **Axes**, click _Add an axis_. The module first suggests a color-type attribute group. For each axis, choose the **display** (automatic, color swatch, product photo thumbnail, text button, drop-down list) and the **structured data property** (color, size, material, pattern, or not declared).
3. Under **Products of the group**, search products by name, reference or ID. Arrow keys and Enter select a result. Products already in another group are greyed out.
4. For each product, check the value of each axis. It is pre-filled when it appears in the product name. A missing value is highlighted in orange, and the status line under the table shows how many products are affected, or whether two products share the same values.
5. Save. The module warns you if you leave the page with unsaved changes.

The order of the group rows is the order of the swatches on the shop. The _Sort by attribute order_ button arranges the rows in the order set in the catalog, handy for sizes S, M, L, XL.

## What shoppers see

On each page of the group, the selector shows the axis name and the current value, for example _Color: Red_, then the available values. On hover, the label shows the pointed value. The current value is outlined; the others are links to the matching page.

- With several axes, clicking a color opens the product that keeps the current size. If that combination does not exist, the module opens the closest variant, preferring a product in stock, and the swatch gets a dashed border.
- An out-of-stock variant is faded and struck through, or hidden depending on the setting.
- A color value with no hex code or texture is shown as text in a pill-shaped swatch.
- The selector also appears in the quick view of category pages, above the add-to-cart button.

## Module settings

- **Selector position**: before the native combinations block (recommended), after that block, in the `displayProductAdditionalInfo` hook, or only in the `displayDfProductLinker` theme hook.
- **CSS selector of the native combinations block**: `.product-variants, .product__variants` by default. If nothing matches in your theme, the selector stays in the hook.
- **Axis label**, **price of each variant** (image and button modes), **image format** of thumbnails.
- **Out-of-stock variants**: faded or hidden.
- **Accent color**, swatch **shape** (round or square with rounded corners) and **size**. The medium size gives a 44 px touch area, recommended on mobile.
- **Swatches in product listings**, maximum number of swatches, and **image change on hover**.
- **Single product per group**, visibility of the other products and product shown: see the next section.
- **Canonical URL of the variants** and **ProductGroup structured data**: see the SEO section.

For custom placement, choose the _theme hook_ position and add this line to your theme's product template: `{hook h='displayDfProductLinker' product=$product}`.

## Single product per group in category pages

This option shows a single card per group in category listings. The other products of the group switch to _Search only_ visibility (or _Nowhere_, depending on the setting): their pages stay online with their URL, and the card swatches link to them.

- **Product shown**: the first of the group, or the first in stock. In the second case, the product shown is recalculated on every stock movement.
- The original visibility of each product is saved. It is restored when you disable the option, deactivate the group, remove a product from its group or uninstall the module.
- If you manually change the visibility of a hidden product, your value becomes the new original value.
- The _Resynchronise the visibility_ button in the configuration reapplies the rule to every group. Use it if products were edited by an employee without permission on the module, since PrestaShop then does not trigger the module's hooks.

Before enabling the option, check that your sitemap generator includes products with _Search only_ visibility, otherwise the hidden variants would drop out of the sitemap.

## SEO: structured data and canonical URL

The module adds a `ProductGroup` JSON-LD block with `hasVariant` and `variesBy` on each page of the group. Each variant is listed with its name, URL, reference, EAN13 when valid, image, value on each axis, the price shown to the shopper and its availability. The group name is taken from the product name without its values, in the visitor's language. Disable the option if another module already outputs this block.

By default, each variant keeps a self-referencing canonical URL: each color is indexed on its own. If your color pages are near duplicates, the _Canonical to the main product of the group_ option points the canonical of every variant to the main product, meaning the product shown in listings when the single product per group option is on, otherwise the first active product of the group.

## Auto-grouping assistant

From the group list, click _Auto-grouping assistant_. It finds products that are the same item in several colors or sizes.

1. Choose a category, or the whole catalog.
2. Tick the attribute groups to detect, for example Color and Size. The values must exist as attribute values and appear in the product name.
3. Choose the rule: identical names once the values are removed, or references sharing the same root (TSH01-RED and TSH01-BLUE).
4. Click _Preview_, untick the groups to skip, then _Create the selected groups_.

Products already in a group are skipped, and the scan covers 5,000 products per run.

## CSV import and export

The _CSV import / export_ button opens the dedicated page. The export writes one line per product, in the same format as the import. Columns:

```
group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Color|Size;;TSH01-NAVY-M;;Color:Navy blue|Size:M
```

- A group is matched by `group_id`, otherwise by its exact name. Each group present in the file is replaced by its lines; groups absent from the file are not modified.
- A product is found by `product_id`, otherwise by `product_reference`, which must be unique in the catalog. `product_name` is informative.
- `values` holds Axis:Value pairs separated by `|`, using attribute group and value names in any language of the shop.
- The `;` or `,` separator is detected automatically. UTF-8 file, 5 MB maximum.

The import runs in two steps: _Analyze the file_ shows the groups created or replaced, the attribute values that will be created and every rejected line with its reason; _Run the import_ then executes it. Two options: _Move products that already belong to another group_ and _Create missing attribute values_ (their color stays empty, to be completed in the catalog).

## Back-office product page

In the Modules tab of the product page, the DF ProductLinker panel shows the product's group and the value of each product of the group, with a link to edit the group. If the product is in no group, a link creates a group from this product.

## Frequently asked questions

### The selector does not appear on a page

Check that the group is active, that the page belongs to the group, that at least two products of the group are active and that at least one axis has two different values. If you chose the theme hook position, the `displayDfProductLinker` hook must be present in the product template.

### The selector shows below the add-to-cart button

The CSS selector of the native combinations block matches no element in your theme. Enter the class of your theme's combinations block in the configuration.

### Swatches do not appear in listings

The option must be enabled, and the first axis of the group must be displayed as color swatches or photo thumbnails. Your theme must call the native `displayProductListReviews` hook in the product miniature, as the Classic theme does.

### Can I combine the module with native combinations?

Yes. A common case: one product per color, each with size combinations. The module's selector handles colors, the native block handles sizes.