# Widget reference

`embed.js` turns a container into the ShowroomPro ring builder. It is a single small script with no dependencies. Your quiz token is the `quizToken` from the [sandbox API](https://www.showroompro.ai/docs/sandbox-api.md), or the token in **Settings → Embed** in the ShowroomPro dashboard. Replace `YOUR_TOKEN` below with it. The token is public and safe to put in page code.

## Display modes

### Inline (recommended)

The ring builder renders inside the page. The iframe grows and shrinks with the quiz, so there is no fixed height and no inner scrollbar.

```html
<div data-showroompro-ring-builder="YOUR_TOKEN"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>
```

### Floating launcher

A "Design your ring" button stays in the corner of every page and opens the ring builder in a popup. Put it in the site-wide footer or layout.

```html
<script src="https://www.showroompro.ai/embed.js" data-token="YOUR_TOKEN" data-mode="floating" async></script>
```

### Popup button

A button appears where the container sits and opens the ring builder in a popup.

```html
<div data-showroompro-ring-builder="YOUR_TOKEN" data-mode="popup"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>
```

### Your own button or link

Load the script with your token and no mode, then point any link at `#showroompro-ring-builder`. Nothing is drawn until the link is clicked.

```html
<script src="https://www.showroompro.ai/embed.js" data-token="YOUR_TOKEN" async></script>

<a href="#showroompro-ring-builder">Design your ring</a>
<a href="#showroompro-wedding-band">Design your wedding band</a>
```

Any element with `data-showroompro-open="YOUR_TOKEN"` also opens the popup on click, and `data-quiz="wedding-band"` on that element opens the wedding band path.

## Wedding bands

Add `data-quiz="wedding-band"` to the container (or to the script tag for the floating launcher):

```html
<div data-showroompro-ring-builder="YOUR_TOKEN" data-quiz="wedding-band"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>
```

This starts the quiz with **Wedding band** selected. It has no effect unless the Wedding Band Builder is turned on for the account.

## Attributes

Set these on the container, or on the script tag for the floating launcher.

| Attribute | Values | Default |
| --- | --- | --- |
| `data-showroompro-ring-builder` | your token (container only) | — |
| `data-token` | your token (script tag, or container) | — |
| `data-mode` | `inline`, `floating`, `popup` | `inline` for containers |
| `data-quiz` | `engagement`, `wedding-band` | `engagement` |
| `data-label` | button text | "Design your ring" ("Design your band" for wedding bands) |
| `data-position` | `bottom-right`, `bottom-left` (floating only) | `bottom-right` |
| `data-color` | any CSS color for the button background | the brand color set in ShowroomPro |
| `data-text-color` | any CSS color for the button text | white |
| `data-min-height` | inline minimum height in px (300–2000) | `600` |

Branding inside the quiz (logo, colors, welcome text, which options shoppers can pick, language) is set in the ShowroomPro dashboard, not with attributes.

## Behavior you can rely on

- **One script per page.** Loading `embed.js` twice is harmless; the second copy does nothing.
- **Late containers mount automatically.** The script watches the page, so containers added by React, Vue, Next.js or a page builder after load are mounted without extra code. Call `ShowroomPro.mount()` to force it.
- **Mobile.** Inline mode fits the container width. The popup is full screen on phones.
- **Install detection.** When the widget loads on a real domain, ShowroomPro records the domain and the dashboard shows **Live on: yoursite.com**. Localhost and raw IP addresses are not recorded. A wrong token logs a warning in the browser console.

## JavaScript API and events

`embed.js` exposes `window.ShowroomPro`:

```js
ShowroomPro.open();                          // open the popup
ShowroomPro.open({ quiz: "wedding-band" });  // open the wedding band path
ShowroomPro.close();                         // close the popup (no confirmation)
ShowroomPro.isOpen();                        // true while the popup is open
var stop = ShowroomPro.on("design_generated", function (detail) {
  console.log("design ready", detail.sessionId);
});
stop();                                      // or ShowroomPro.off(name, fn)
ShowroomPro.on("*", function (detail) { console.log(detail.event, detail); });
ShowroomPro.mount();                         // mount containers added after load
```

The same events are dispatched as DOM events named `showroompro:<event>`. They fire on the container (or the button that opened the popup) and bubble up to `window`. Listen for `showroompro:ready` if you need to know when the API is available:

```js
window.addEventListener("showroompro:ready", function () {
  document.querySelector("#my-button").onclick = function () { ShowroomPro.open(); };
});
```

| Event | When | Detail |
| --- | --- | --- |
| `ready` | widget initialized | `version` |
| `open` / `close` | popup opened / closed | `mode`, `quiz` |
| `quiz_started` | the shopper entered their details and the quiz session started | `sessionId` |
| `design_generated` | designs were generated | `sessionId` |
| `band_quiz_complete` | wedding band quiz submitted | `sessionId` |
| `design_approved` | the shopper approved a design | `sessionId` |
| `design_created` | a design was created (see [conversion tracking](https://www.showroompro.ai/docs/tracking.md)) | `design_id`, `timestamp` |
| `resize` | inline iframe height changed | `height` |

Every lifecycle event detail also includes `event`, `mode` and `quiz`. Events never contain the shopper's name, email or phone number. Leads stay in the dashboard, or arrive through [webhooks](https://www.showroompro.ai/docs/webhooks.md).

Older installs may listen for `ringbuilder:quiz_started`, `ringbuilder:design_generated` and `ringbuilder:design_approved`. These aliases still fire.

## Iframe fallback

Some site builders remove `<script>` tags. In that case use a plain iframe:

```html
<iframe src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN" width="100%" height="800" frameborder="0" style="border:none;"></iframe>
```

For wedding bands, add `&quiz=wedding-band` to the URL. The iframe has a fixed height, does not resize with the quiz, and is not counted for install detection. Use the script snippets whenever the platform allows them.

### Auto-resizing a hand-written iframe

Add `sp_autosize=1` to the URL (optionally `sp_min_height=700`). The quiz then posts its height and you resize the iframe yourself:

```html
<iframe id="sp-quiz" src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN&sp_autosize=1" style="width:100%;border:0;height:600px"></iframe>
<script>
  window.addEventListener("message", function (e) {
    if (e.origin !== "https://www.showroompro.ai") return;
    if (e.data && e.data.type === "showroompro:resize") {
      document.getElementById("sp-quiz").style.height = e.data.height + "px";
    }
  });
</script>
```

## Existing installs keep working

Nothing on an existing site needs to change. These older forms still work:

- `<script src="…/embed.js?token=YOUR_TOKEN"></script>` with links to `#ringbuilder-quiz`, or elements with `data-ringbuilder-quiz="YOUR_TOKEN"`
- `<iframe src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN">`
- script tags loaded from `ringbuilder.ai` or `showroompro.ai`

Use the snippets above for new installs.

## Content Security Policy

If the site sends a `Content-Security-Policy` header, allow ShowroomPro:

```text
script-src  https://www.showroompro.ai;
frame-src   https://www.showroompro.ai;
connect-src https://www.showroompro.ai;
```

Add these to the directives you already have rather than replacing them.

## Troubleshooting

- **Nothing appears.** Check the browser console for `[ShowroomPro]` warnings. Make sure the token is right and the script URL is exactly `https://www.showroompro.ai/embed.js`.
- **The builder removed my script.** Use the [iframe fallback](#iframe-fallback), or the platform's site-wide code injection (see the [install guides](https://www.showroompro.ai/docs/install.md)).
- **Dashboard says "not live yet".** Load the page on the real domain, not a preview or localhost URL.
- **Inline widget is cut off.** A parent element has a fixed height or `overflow: hidden`. Remove it, or use popup mode.

---

Source: https://www.showroompro.ai/docs/widget · Last updated 2026-10-16 · All docs: https://www.showroompro.ai/llms.txt