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

# The widgets

> [!WARNING]
>
> This feature is in **beta**. This means it might at any time be changed, withdrawn from your account, or become part of a paid add-on module. You might also experience interruptions of this service, degradation of user experience or faulty behavior even in critical processes such as automations and sendouts. Voyado welcomes feedback on beta features, and encourages you to try them, but you should *not* build business critical logic on beta features. Only when a feature reaches its full release can you trust it to function reliably with no further breaking changes.

## Widget Containers (HTML)

Place `<div>` containers anywhere in your HTML. These containers must be pure HTML, they *cannot* be injected by GTM. They must be part of your page templates.

> [!TIP]
>
> For all widgets below set **all** the following attributes on each container, in this order:

| Attribute | Required | Description |
| - | - | - |
| `data-product-group-id` | **Yes** | Product group identifier (for variant grouping) |
| `data-product-id` | **Yes** | Product identifier |
| `data-variant-id` | **Yes** | Specific variant identifier |

Example values are:

* `data-product-group-id` = "Product"
* `data-product-id` = "Product-Color"
* `data-variant-id` = "Product-Color-Size"

Here are the available widgets in more detail, along with where they are shown.

* PLP = Product Listing Page
* PDP = Product Detail Page

> [!WARNING]
>
> Either the Badge widget ("voyado-badge") or the Add Review widget ("voyado-add-review") or both must be present on the product detail page (PDP). This is to ensure that the variant structure is known when the customer writes a review in the review pop-up.

### Ratings widget (PDP & PLP)

This is an inline star \ score count. It is typically placed near the product title.

```html Ratings widget theme={null}
<div class="voyado-ratings voyado-ratings--small"
     data-product-group-id="560R"
     data-product-id="560R-Strawberry"
     data-variant-id="">
</div>
```

Variants:

* `voyado-ratings--small` (16 px text)
* `voyado-ratings--vertical` (stacked layout)
* Or both combined.

### Badge widget (PDP — sidebar)

This includes a large numeric score, stars, a review count and a "Review this product" CTA that opens the review popup.

```html Badge widget theme={null}
<div class="voyado-badge"
     data-product-group-id="Product"
     data-product-id="Product-Color"
     data-variant-id="Product-Color-Size">
</div>
```

Variants:

* `voyado-badge--compact` for a smaller score (48 px instead of 78 px with CTA hidden)

### Summary widget (PDP)

This includes AI generated sentiment highlights from customer reviews. It is automatically hidden when there are no reviews.

```html Summary widget theme={null}
<div class="voyado-summary"
     data-product-group-id="Product"
     data-product-id="Product-Color"
     data-variant-id="Product-Color-Size">
</div>
```

### Reviews widget (PDP)

This is a full review list with sort dropdown, pagination, author, date, star rating, text, verified-buyer badge, thumbs up/down voting, and comment threads. Authenticated users can edit their own reviews.

```html Reviews widget theme={null}
<div class="voyado-reviews"
     data-product-group-id="Product"
     data-product-id="Product-Color"
     data-variant-id="Product-Color-Size">
</div>
```

Variants:

* `voyado-reviews--boxed` wraps each review in a card

### Highlights widget (PLP / PDP)

This is a single AI-selected review excerpt including title, date, and a "Powered by Voyado" footer. It is lighter than the full Summary widget.

```html Highlights widget theme={null}
<div class="voyado-highlights"
     data-product-group-id="Product"
     data-product-id="Product-Color"
     data-variant-id="Product-Color-Size">
</div>
```

### Distribution widget (PDP — rating breakdown)

Five-row breakdown (5★ down to 1★), each row showing a mini star icon, the review count for that star value in parentheses, and a horizontal bar sized to that rating's share of all reviews.

This is the widget referenced internally as "rating breakdown (5★/4★/3★…)."

```html Distribution widget theme={null}
<div class="voyado-distribution"
     data-product-group-id="g-w001"
     data-product-id="w001"
     data-variant-id="w001-xs-black">
</div>
```

### Carousel widget (PDP — scrolling review cards)

A horizontally-scrolling row of review cards under the heading "What our customers are saying," with prev/next nav buttons.

Supports two optional filtering attributes not used by any other widget:

* `data-min-rating`: Include only reviews at or above this star rating (for example, 4 means show only 4 and 5 star reviews)
* `data-max-review-count`: Cap the number of review cards rendered (for example, to 10)

```html Carousel widget theme={null}
<div class="voyado-carousel"
     data-product-group-id="g-w001"
     data-product-id="w001"
     data-variant-id="w001-xs-black"
     data-min-rating="4"
     data-max-review-count="10">
</div>
```

### Add Review widget (PDP — standalone collection button)

A standalone CTA button that opens the review-submission modal directly.

```html Add Review widget theme={null}
<button class="voyado-add-review"
    data-product-group-id="g-w001"
    data-product-id="w001"
    data-variant-id="w001-xs-black">
  Add a review
</button>
```

## Loading widgets

This is how the widgets are loaded:

```javascript Loading widgets theme={null}
voyado('load-widgets', [types])
```

You will replace \[types] here by the list of widgets you want to load. Available are:

* "ratings"
* "badge"
* "summary"
* "reviews"
* "highlights"
* "distribution"
* "carousel"
* "add-review"

```javascript PLP example theme={null}
voyado('load-widgets', ['ratings']);
```

```javascript PDP example theme={null}
voyado('load-widgets', ['badge', 'ratings', 'summary', 'reviews', 'distribution', 'carousel', 'add-review']);
```

> [!WARNING]
>
> Make this call to load the widgets *after* the widget containers are in the DOM.. Only use the widget types that are present on the current page; listing absent types wastes DOM searches.

### Clearing widgets

To clear the loaded widgets, call:

```javascript theme={null}
voyado('reset-widgets')
```

Call this before a SPA route change, then call `load-widgets` again after the new view is rendered.

### Keeping widget attributes in sync

It's important to always keep widget attributes in sync with the selected variant.

This means you should always ensure that the attributes `data-product-group-id`, `data-product-id` and `data-variant-id` match what the shopper is currently viewing on the page and not just contain the values present when the initial page load was done.

Whenever the shopper changes size, color, or otherwise selects a different variant, update these three attributes on *every Voyado widget present on the page* (such as .voyado-badge, .voyado-add-review, and any others you've added):

If you don't do this, the attributes will be never updated, meaning a shopper who switches variant will end up submitting — or viewing — reviews for the wrong product and/or variant.

> [!WARNING]
>
> Always keep widget attributes `data-product-group-id`, `data-product-id`, `data-variant-id` in sync with what the customer is currently viewing.

#### If no variant is selected

If the merchant hasn't selected a variant on the site (for example, the shopper is on a product page where no size or color is chosen yet), set `data-variant-id` to an empty value on the widgets.

Do *not* leave a stale variant from an earlier selection.

#### Links from review-request emails

When a visitor arrives at your site through a link in a review-request email, the link also carries a `voyado-rating-item` parameter. The script then:

* Looks for other Voyado widgets on the page, such as `voyado-badge` or `voyado-add-review`
* Reads `data-product-group-id`, `data-product-id` and `data-variant-id` from the widgets and uses only the attributes that have values
* If there is no widget, or all three attributes are empty, it will fall back to the value in `voyado-rating-item`

For example, consider when a customer buys "variant 107-blue-xl", and that value is added to the email link as the value for `voyado-rating-item`.

When the customer follows this link, the script gets this information on your site and tries to set it as `data-variant-id` in the `voyado-badge` and `voyado-add-review` widgets, but only if that attribute is empty. Here `data-product-group-id` and `data-product-id` have already been set by the script.

> [!TIP]
>
> The script only fills in an empty `data-variant-id`. It never overwrites a value you have already set. If the shopper then selects another variant, be sure to update all three attributes as described above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.