> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/shopping-experience-elements.md).

# Shopping experience elements

All Shopping Experience elements of Cross Selling Pro, their card layouts, plan limits and every field in the Shopping Experience editor.

With the Shopping Experience elements of Cross Selling Pro you can add recommendations to any Shopware Shopping Experience: on the home page, on category pages, on landing pages and in the product page layout. Each element stands for one fixed card layout. Which products appear is decided by the recommendation template you select in the element.

This page is a reference: here you find all elements, all card layouts with the plan they require and all fields the Shopping Experience editor offers.

## Before you start

You need at least one [recommendation template](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/recommendation-templates.md). Without a template, the element shows the notice "No templates available" in the editor, together with the button "Create template".

A template only appears in the shop once it is used in an element or at a [placement](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/placements.md).

## How the elements work in the shop

A few rules apply to all elements in the same way. They answer most questions that come up after adding an element.

* **Products are loaded afterwards.** When the page is opened, the element briefly shows "Loading recommendations...". The visitor's browser then builds the cards. This means personal data of the visitor never ends up in the cached page content.
* **No recommendations, no block.** If nothing comes back for an element, it removes itself completely. No empty area and no notice text remain. If you want to avoid this, set up a fallback in the template (see [Images, prices, fallbacks and visibility](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/images-prices-and-fallbacks.md)).
* **Plan limits are invisible in the shop.** If the card layout or the recommendation type of the template is not part of your plan, the shop shows nothing at this spot, without a notice and without a fallback. In the editor, the element then shows "Not displayed · Available from …" with the link "View plans".
* **The source product is always excluded.** On a product page, the current product and its variants are never recommended. More on the [Product page](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/product-page.md) page.

## Adding an element

{% stepper %}
{% step %}

### Open the Shopping Experience

1. In the Shopware Administration, open **Content → Shopping Experiences**.
2. Open the Shopping Experience you want or create a new one. For recommendations based on the product currently viewed, choose a layout of the type product page.
   {% endstep %}

{% step %}

### Insert a block

1. Open the blocks in the right sidebar and choose the block category **"AI CrossSelling"**.
2. Drag the block you want to the right position. The block name tells you the card layout, for example "AI CrossSelling: Standard-Karten".
   {% endstep %}

{% step %}

### Configure the element

1. Click the element. The settings open on the right with the tabs "Settings" and "Design".
2. Under "Recommendation template", select the template.
3. Enter a title and subtitle if needed and switch brand, description, badges and price on or off as you like.
   {% endstep %}

{% step %}

### Save and assign

1. Click **Save**.
2. Assign a new layout to its page: to a category (tab "Layout" in the category), to a single product (tab "Layout" in the product) or as the default layout.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
You can place several elements with different templates on the same page, for example "Bestseller" at the top and "Recently viewed" further down.
{% endhint %}

## All elements at a glance

In the block category "AI CrossSelling" you find nine recommendation elements and two special elements. The names are always shown in German in the Administration, even if the Administration is set to English.

| Element in the editor            | Card layout                          | Kind        | Available from plan |
| -------------------------------- | ------------------------------------ | ----------- | ------------------- |
| AI CrossSelling: Standard-Karten | portrait cards with the image on top | slider      | Basic               |
| AI CrossSelling: Minimal         | very compact mini cards              | slider      | Basic               |
| AI CrossSelling: Kompakt         | small cards, image on the left       | slider      | Starter             |
| AI CrossSelling: Große Kacheln   | wide cards with brand                | slider      | Starter             |
| AI CrossSelling: Detailkarten    | large cards with description         | slider      | Expert              |
| AI CrossSelling: Raster          | card grid                            | static      | Expert              |
| AI CrossSelling: Liste           | entries below each other             | static      | Expert              |
| AI CrossSelling: Mosaik          | tile block with a text area          | static      | Expert              |
| AI CrossSelling: Spotlight       | large and small cards mixed          | static      | Expert              |
| Cogi Bundle/Set Configurator     | set configurator                     | own element | Expert              |
| Cogi Conversion Booster Overlay  | product window with alternatives     | own element | Advanced            |

Besides the layout, the **recommendation type of the template** must also be included in your plan. Which type is available from which plan is listed on the page [Requirements and plans](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/requirements-and-plans.md).

{% hint style="warning" %}
There is no longer a "Slider design" selection field in the element. You choose the card layout through the block alone. To switch the layout, insert a different block and select the same template there.
{% endhint %}

## The card layouts in the shop

### Slider layouts

Standard-Karten, Minimal, Kompakt, Große Kacheln and Detailkarten are sliders. They show arrows and dots, do not move on by themselves and jump back to the start at the end. On mobile devices (below 768 px width) the visitor swipes with a finger.

How many cards are shown side by side is calculated by the slider from the width of the available space and the minimum width of a card. In a narrow space there are fewer cards, on a wide page more. At least one card is always visible.

| Layout          | Minimum card width |
| --------------- | ------------------ |
| Standard-Karten | 220 px             |
| Detailkarten    | 260 px             |
| Minimal         | 320 px             |
| Kompakt         | 340 px             |
| Große Kacheln   | 360 px             |

### Static layouts

Raster, Liste, Mosaik and Spotlight show the products without a slider.

* **Raster (grid):** cards in columns, each column at least 210 px wide. On small screens (below 576 px) always two columns. The product name takes up at most two lines.
* **Liste (list):** entries below each other, the image sits on the left at the height of the row. Badges are always off in this layout.
* **Mosaik (mosaic):** a block of two or four tiles, next to it a free text area. On mobile devices, tiles and text are shown below each other.
* **Spotlight:** one or two large cards, next to them smaller ones. The large card takes up two by two fields. Depending on the screen width there are four, three, two or one column.

### What a card shows

Depending on the switches in the element, a card shows: product image, badges (for example "Topseller" or your own badges), brand, product name, short description, price and a button. If there is a list price, it appears with the saving in percent. Products with variants at different prices show a "from" price without a list price.

Image and name lead to the product page.

### The button on the card

What the button does is set in the template in the field "Button action":

| Option                   | Effect in Shopping Experience elements                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| "Show details" (default) | opens the product page                                                                                                         |
| "Add to cart"            | adds one item to the cart and opens the offcanvas cart                                                                         |
| "Details + cart"         | only works in the offcanvas cart and on the cart page. In Shopping Experience elements the button behaves like "Show details". |

Special cases:

* **Products with variants** show "Choose variant". A window with the variant selection and the buy area of the product page opens, so the visitor adds the right variant.
* **Products that must be personalised** (Printess, Custom Products, your own configurator) are never added to the cart directly. Depending on the setting, the card shows "Design now" and opens the editor, or it leads to the product page. Details on the page [Working with other plugins](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/working-with-other-plugins.md).

## Fields in the Shopping Experience editor

All nine recommendation elements use the same settings. At the very top is the button **"Open widget stats"**. It opens the statistics of exactly this element in a new tab.

### Tab "Settings"

| Field                     | Effect in the shop                                                                 | Default                                                |
| ------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ |
| "Title"                   | heading above the cards. Empty means: no heading.                                  | empty                                                  |
| "Subtitle"                | smaller line below the heading                                                     | empty                                                  |
| "Show Brand"              | manufacturer name on the card                                                      | on for Große Kacheln, otherwise off                    |
| "Show Description"        | short description text on the card                                                 | on for Detailkarten, otherwise off                     |
| "Show Badges"             | badges such as Topseller, Sale or New                                              | on for Standard-Karten and Detailkarten, otherwise off |
| "Show Price"              | price on the card                                                                  | on                                                     |
| "Recommendation template" | which template provides the products. Next to it is the button "Manage templates". | none                                                   |

Special features per layout:

* **Kompakt and Minimal** have no switches for brand and description. Both stay off in the shop.
* **Liste** has no switch for badges. Badges stay off.
* If the layout is not included in your plan, a plan lock lies over the settings.

{% hint style="info" %}
You do not set the **number of products** in the element but in the template, in the field "Limit" (1 to 50). If the template has no value, the element shows up to 6 products.
{% endhint %}

### Additional fields for Mosaik

| Field                      | Options                                                           | Default    |
| -------------------------- | ----------------------------------------------------------------- | ---------- |
| "Tile position"            | "Tiles left, text right", "Tiles right, text left"                | tiles left |
| "Width ratio"              | "Larger tiles (60/40)", "Balanced (50/50)", "Larger text (40/60)" | 50/50      |
| "Tile size"                | Small, Medium, Large                                              | Medium     |
| "Tile Count"               | "4 Tiles (2×2)", "2 Tiles (1×2)"                                  | 4 tiles    |
| "Enable Horizontal Slider" | on, off                                                           | off        |
| "Text area"                | free text with formatting                                         | empty      |

This is how the slider switch works: when it is off, the mosaic shows exactly two or four tiles, further products of the template are left out. When it is on, the tiles themselves become a swipe slider with arrows and dots that contains all products of the template. If you leave the text area empty, the tiles take up the full width.

### Additional fields for Liste

| Field                    | Limits                   | Default |
| ------------------------ | ------------------------ | ------- |
| "Row height (px)"        | 48 to 400, in steps of 8 | 96      |
| "Enable vertical slider" | on, off                  | off     |
| "Visible items"          | 1 to 20                  | 4       |

With the vertical slider, the visitor scrolls within the list when the template delivers more products than items are visible.

### Additional fields for Spotlight

| Field                    | Options                                                       | Default           |
| ------------------------ | ------------------------------------------------------------- | ----------------- |
| "Spotlight Mode"         | "1 Large + 4 Small", "1 Large + 2 Small", "2 Large + 4 Small" | 1 Large + 4 Small |
| "Featured Item Position" | Left, Right                                                   | Left              |

Depending on the mode, Spotlight shows at most 5, 3 or 6 products. If the template delivers more, the rest are left out.

### Tab "Design"

At the top is the notice "Leave empty = values are inherited from the theme (default)." Everything you do not fill in here is taken from your theme.

| Section              | Fields                                                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| "Typography"         | "Font size (px)" (8 to 80), "Font weight" (Default, Normal, Medium (500), Semibold (600), Bold (700))                         |
| "Add-to-cart button" | "Font size (px)" (8 to 60), "Font weight", "Colour" (Default, Primary, Secondary, Success (green), Danger (red), Dark, Light) |
| "Custom classes"     | "CSS classes" for your own styling, several separated by spaces                                                               |

## The two special elements

**Cogi Bundle/Set Configurator** shows a small set configurator. It only works in the layout of a product page. Fields: "Title", "Subtitle" and "Set template". Behaviour and product source are defined in the set template. More on the page [Bundle and set templates](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/bundle-and-set-templates.md).

**Cogi Conversion Booster Overlay** also belongs in the product page layout and only appears when the address contains a specific parameter. All fields are described on the page [Conversion Booster](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/conversion-booster.md).

## Good to know

* **Pages without a product:** The home page, category pages and landing pages have no current product. Types that need a source product (for example "Similar products (alternatives)") usually deliver nothing there, and the element disappears. Use types such as "Bestseller", "Trends", "Personal" or "Recently viewed" there, or set a fixed reference product in the template.
* **Changes to the template** take effect immediately: when you save, Shopware discards the cached pages that use this template. Changes to the element settings follow the normal Shopware cache. More on the page [When do changes take effect?](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/when-changes-take-effect.md).
* **Deleting a template:** A template is deleted without a confirmation prompt. Elements that use it show nothing afterwards.
* **Themes:** The cards are built for the Shopware default theme and take over colours and fonts of the theme. With themes that have a strongly individual style, adjustments via the "Design" tab or your own CSS classes may be needed.

## Read more

{% content-ref url="/pages/hSRY2MxmbdY5dCCa9KY4" %}
[Creating recommendation templates](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/recommendation-templates.md)
{% endcontent-ref %}

{% content-ref url="/pages/v0RzTVJFjsXNoeFkgj6R" %}
[Product page](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/product-page.md)
{% endcontent-ref %}

{% content-ref url="/pages/mKxITzjqofyIV1LBMwPL" %}
[Conversion Booster](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/conversion-booster.md)
{% endcontent-ref %}

{% content-ref url="/pages/vqIfuf09tAiEW3Hoc7Ya" %}
[Images, prices and fallbacks](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/images-prices-and-fallbacks.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/shopping-experience-elements.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
