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

# Reviews widget

> Embed your verified client reviews on your own website with a single line of code.

The **Reviews widget** lets you display your published Winnerr reviews — plus your star aggregate — directly on your personal real estate website. You create the widget in Winnerr, copy one line of code, and paste it where you want reviews to appear.

Managed under **Marketing → Reputation → Widgets**.

## How it works

The widget loads as an inline iframe. Winnerr serves a small loader script from the API; that script finds its mount point on your page and injects a responsive iframe pointing at your hosted reviews page. The iframe auto-resizes to fit its content. No third-party JavaScript framework is required on your site.

The widget only ever displays reviews you have already approved and published in Winnerr. Nothing drafts or pending is shown.

## Create a widget

You must have a published reputation profile before you can create a widget. If your profile is still a draft, publish it first under **Reputation → Profile**.

1. Go to **Marketing → Reputation → Widgets**.
2. Click **Create widget**. Winnerr generates a unique embed key (`publicKey`) for this widget and adds it to your list.
3. Configure its appearance and origin settings (see below).
4. Click **Save changes**.
5. Copy the snippet and paste it into your website.

## Appearance settings

Each widget has four configurable appearance options:

| Setting             | Options                     | Default   |
| ------------------- | --------------------------- | --------- |
| Layout              | List, Grid, Carousel, Badge | List      |
| Accent color        | Any hex color               | `#17130f` |
| Max reviews         | 1–50                        | 12        |
| Show star aggregate | On / Off                    | On        |

**List** stacks review cards vertically. **Grid** shows two columns. **Carousel** scrolls horizontally. **Badge** renders a compact rating chip — useful for footers or sidebars.

The aggregate (total reviews, average star rating) appears above the review cards when **Show star aggregate** is on.

## Origin allowlist

The widget data endpoint enforces a per-widget origin allowlist. Only requests from origins you list will receive review data; any other origin gets a `403`.

Enter one bare origin per line (scheme and host only, no path):

```text theme={null}
https://www.janesmith.com
https://janesmith.com
```

Leave the list empty to allow any origin. This is less secure and not recommended if your widget key could be misused.

## The embed snippet

After saving, copy the snippet from the **Embed snippet** section of the widget card:

```html theme={null}
<script src="https://api.winnerr.ai/api/reputation/widget?key=YOUR_PUBLIC_KEY" async></script>
```

Paste this anywhere in your page's HTML where you want the reviews to appear. By default the widget inserts itself immediately before the script tag.

To control exactly where the reviews render, add a `data-winnerr-reviews` attribute to any container element:

```html theme={null}
<div data-winnerr-reviews></div>
<script src="https://api.winnerr.ai/api/reputation/widget?key=YOUR_PUBLIC_KEY" async></script>
```

You can also preview the widget in a new tab before embedding it using the **Preview** button on the widget card.

## Pausing and disabling

Use the **Live** toggle on any widget card to pause it (`PAUSED`). A paused widget returns `404` on the data endpoint so the iframe shows nothing — useful when you want to temporarily hide reviews without deleting the embed from your site.

A `DISABLED` widget cannot be toggled back on from the UI and is effectively retired.

## What the widget exposes

The widget data endpoint returns only:

* Reviews with status `PUBLISHED` and visibility `PUBLIC`.
* Consent-allowed public fields: display name, location, and photo (only when the client granted photo permission).
* The reputation aggregate (rating, NPS, response rate, review velocity).

No client contact information, deal IDs, draft review content, or internal Winnerr data is ever included in the widget response.

## Related

* [Testimonials](/reputation/testimonials) — approve and publish reviews so they appear in the widget.
* [Public profile](/reputation/public-profile) — must be published before a widget can be created.
* [Reputation overview](/reputation/overview) — the full Reputation Studio flywheel.