> ## Documentation Index
> Fetch the complete documentation index at: https://help.maestra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Create a Recommendation Widget

A recommendation widget shows personalized product blocks on your website — bestsellers on the homepage, related items on a product page, "you might also like" on the cart, and so on. The widget engine (PopMechanic) renders the block, while Maestra Platform supplies the recommendation algorithm and the product data behind it.

This guide walks through creating a recommendation widget from scratch, choosing a template, configuring targeting and algorithms, and launching it on your site.

<Note>
  Before you start, make sure the integrations required for recommendation widgets are in place — the Maestra tracker on every page, product feed synchronization, and real-time event tracking. See [Required Integrations for Recommendation Widgets](/personalization/recommendation-widgets/required-integrations-for-recommendation-widgets) for the full checklist.
</Note>

## Step 1. Create a new widget

In Maestra Platform, go to **Campaigns** and click **Create campaign**. Choose **Personalization → Recommendation widget**.

## Step 2. Pick a template

You have three templates to start from. Pick the one that matches what you're building — you can edit the markup and styling afterward.

<CardGroup cols={3}>
  <Card title="Basic template" icon="square">
    A clean product card with product name, current price, old price, and discount badge. The fastest way to get a working widget on the page.
  </Card>

  <Card title="Extended template" icon="layer-group">
    Adds extra product fields and JavaScript handlers — useful when you need things like add-to-cart buttons, favorite toggles, or color swatches inside the card.
  </Card>

  <Card title="Pop-up with recommendations" icon="window-restore">
    A modal pop-up that uses a recommendation algorithm for its content. Use it for exit-intent offers or "complete the look" overlays.
  </Card>
</CardGroup>

## Step 3. Configure widget settings

Once you've chosen a template, the widget editor opens. Fill in the following:

* **Widget name** — used internally to find the widget later. Be specific (for example, `Homepage bestsellers — desktop`).
* **Appearance** — edit the product card and widget container markup, and tweak the CSS. See [How to Style a Recommendation Widget](/personalization/recommendation-widgets/how-to-style-a-recommendation-widget) for the details.
* **Display settings** — number of visible product cards per screen size (desktop, tablet, mobile), spacing, autoplay, navigation arrows, and pagination dots.
* **Additional parameters** — autoplay interval, transition speed, and any custom slider options.

<Tip>
  Set up the desktop layout first, then verify mobile separately. A widget that looks great at 1440 px often needs different padding and slide counts at 375 px.
</Tip>

## Step 4. Set targeting

Targeting controls who sees the widget and when. You can limit display by:

* **Customer segment** — for example, only show the widget to subscribed customers or to first-time visitors.
* **Page URL** — restrict the widget to specific pages (homepage, product pages, category pages).
* **Day of week and time of day** — useful for weekend-only promotions or flash blocks.
* **Traffic source** — show different recommendations to paid-search visitors vs. email click-throughs.
* **Device type** — desktop only, mobile only, or both.
* **Number of visits** — first-time visitors vs. returning customers.

Leave the conditions empty if you want the widget to display to everyone on every page where the container is present.

## Step 5. Choose general settings

Set the external systems the widget integrates with:

* **Website** — pick the site this widget belongs to (relevant for multi-site projects).
* **Product system** — the catalog source the algorithm will draw from.

## Step 6. Pick a recommendation algorithm

Select the algorithm that supplies the products. Each widget supports up to **three algorithms**, which are evaluated in order: if the first algorithm returns fewer products than the widget needs, the second one fills the gap, and so on.

Common combinations:

* **Product page:** Similar products → Related products → Popular products in category.
* **Cart page:** Related products to cart items → Frequently bought together → Bestsellers.
* **Homepage:** Personal recommendations → Popular products in viewed categories → Popular products.

<Note>
  If you haven't created the algorithm yet, set it up first in **Personalization → Product recommendations**. See [How to Create a Bestsellers Preset](/personalization/product-recommendation/recommendation-presets/how-to-create-a-popular-products-algorithm) for an example.
</Note>

## Step 7. Set the display location

Decide where on the page the widget renders. Two options:

### Option A — Embed via CSS selector

Maestra Platform inserts the widget into the element you specify. Provide a CSS selector that points to a stable container on the page — for example, `.homepage-recommendations` or `#cart-cross-sell`.

<Tip>
  If you're not sure which selector to use, install the **SelectorGadget** Chrome extension. Click the target spot on your site, and the extension generates a working selector like `.someClass` or `#someid`.
</Tip>

### Option B — Place the code manually

Copy the container code from the widget editor and paste it directly into your site template at the exact spot you want the widget to appear. Use this option when you need pixel-level control or when the surrounding markup is dynamic.

## Step 8. Test the widget

Before going live, open the **Test link** the editor provides. It loads your site with the widget forced on, regardless of targeting rules, so you can verify:

* The widget renders in the expected spot.
* Product cards show the right fields (image, name, price).
* Navigation, autoplay, and responsive breakpoints work.
* Clicks track correctly (open browser dev tools and confirm the event fires).

If something looks off, jump back into the editor — changes take effect immediately on the test link.

## Step 9. Launch

When the test link looks right, click **Launch**. The widget goes live for all visitors that match your targeting.

After launch, you can:

* **Pause** the widget at any time without losing the configuration.
* **Edit** appearance, targeting, or algorithm — edits take effect the next time the page loads.
* **Duplicate** the widget to spin up a variant for A/B testing.
* **Monitor** clicks and conversions in the widget's stats panel.

<Warning>
  Edits to a live widget propagate to all visitors on the next page load. If you're making a major change (new template, different algorithm), pause the widget first, finish the edits, retest on the test link, then relaunch.
</Warning>

## Next steps

* [How to Style a Recommendation Widget](/personalization/recommendation-widgets/how-to-style-a-recommendation-widget) — edit the product card template, container CSS, and slider behavior.
* [Product Grouping in a Recommendation Widget](/personalization/recommendation-widgets/product-grouping-in-a-widget) — split widget content into tabs by category or other attributes.
* [Required Integrations for Recommendation Widgets](/personalization/recommendation-widgets/required-integrations-for-recommendation-widgets) — full integration checklist.