bugsmash-widget

Embeddable review widget for BugSmash. Add a floating feedback button to any website so reviewers can identify themselves, pin feedback to the page, write rich comments, optionally attach an image, and send everything into a BugSmash widget project.

Setup Flow

1. Create a widget project in BugSmash

Log in to your BugSmash workspace and create a new Widget project. A new widget project with no feedback opens directly to the setup instructions panel, including the generic script tag, npm install flow, and WordPress guidance.

Copy the project ID from the setup panel.

2. Install the widget on your site

Use either the npm package or the script tag snippet. For WordPress, place the script-tag version in a header/footer injection area, theme footer, or a custom code plugin that runs on the pages where you want feedback.

3. Pick the target version

Pass a version number, version label, or version name when you want feedback to land on a specific project version. If version is omitted, BugSmash sends feedback to the latest version.

If comments are paused for the selected version, the widget shows the feedback button in a disabled state.

Installation

npm / ESM

npm install bugsmash-widget

import { BugSmash } from 'bugsmash-widget';

BugSmash.init({
  projectId: 'YOUR_PROJECT_ID',
  version: 2,
});

// or by version name
BugSmash.init({
  projectId: 'YOUR_PROJECT_ID',
  version: 'Release candidate',
});

CDN / Script tag

<script src="https://cdn.bugsmash.io/widget/bugsmash-widget.umd.js"></script>
<script>
  BugSmash.init({
    projectId: 'YOUR_PROJECT_ID',
    version: 2,
  });
</script>

WordPress

Add the script-tag version through your site's header/footer code area or a custom code plugin:

<script src="https://cdn.bugsmash.io/widget/bugsmash-widget.umd.js"></script>
<script>
  window.BugSmash.init({
    projectId: 'YOUR_PROJECT_ID',
  });
</script>

API

BugSmash.init(config)

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | projectId | string | ✓ | — | BugSmash widget project ID | | version | number \| string | — | latest version | Version number (1, 2, …), label (V2), or version name | | position | 'bottom-right' \| 'bottom-left' | — | 'bottom-right' | Button position |

BugSmash.destroy()

Removes the widget from the page.

How it works

1. A floating BugSmash button appears in the configured corner of the page.
2. The first time a reviewer clicks it, the widget asks for their name and stores it locally for future feedback on that project.
3. The widget enters comment mode with a crosshair cursor, viewport border, and element highlight.
4. The reviewer clicks an element or page area to place a numbered pin and open the comment composer.
5. The composer supports bold, italic, ordered lists, browser voice dictation, and one optional image attachment.
6. On submit, the widget sends the rich-text comment HTML, reviewer name, clicked element metadata, viewport state, a browser-rendered screenshot fallback, and the optional attachment to BugSmash.
7. The page DOM is also serialized and gzip-compressed so BugSmash can replay the page in Playwright and render a review screenshot with the pin baked in.
8. After the first feedback item exists, the BugSmash app switches from setup instructions to the normal widget review surface with the preview rail and comments sidebar.

Submitted pins remain visible on the same page path in the reviewer's browser and show the saved comment text on hover.