@plmojica/feedback-widget

A framework-agnostic feedback widget that lets users submit bug reports and feature requests directly as GitHub Issues. Built as a Web Component with Shadow DOM for style isolation.

Features

• Web Component — works with any framework or plain HTML
• Shadow DOM — widget styles are fully isolated from the host page
• GitHub Issues integration — submissions create issues with structured Markdown bodies
• Element selector — users can click any element to attach it to their report
• Screenshots — capture the page, paste from clipboard, or drag-and-drop images
• Configurable — theme colors, border radius, placement, project name, and default labels

Installation

npm install @plmojica/feedback-widget

Or via CDN:

<script src="https://unpkg.com/@plmojica/feedback-widget"></script>

Prerequisites

This widget requires a backend proxy to securely create GitHub Issues and generate client keys. See the backend setup guide for details.

Usage

Via JavaScript (recommended)

import { createFeedbackWidget } from "@plmojica/feedback-widget";

const widget = createFeedbackWidget({
  proxyUrl: "https://your-backend.example.com",
  clientKey: "fwk_xxxxxxxxxxxxxxxxx",
  repo: "owner/repo",
  projectName: "My App",
  theme: {
    primaryColor: "#3b82f6",
  },
});

Via CDN (script tag)

<script src="https://unpkg.com/@plmojica/feedback-widget"></script>
<script>
  FeedbackWidget.createFeedbackWidget({
    proxyUrl: "https://your-backend.example.com",
    clientKey: "fwk_xxxxxxxxxxxxxxxxx",
    repo: "owner/repo",
    projectName: "My App",
  });
</script>

Pin a specific version:

<script src="https://unpkg.com/@plmojica/[email protected]"></script>

Or use jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@plmojica/feedback-widget"></script>

Via HTML attributes

<script src="https://unpkg.com/@plmojica/feedback-widget"></script>

<feedback-widget
  proxy-url="https://your-backend.example.com"
  client-key="fwk_xxxxxxxxxxxxxxxxx"
  repo="owner/repo"
  project-name="My App"
></feedback-widget>

Via configure() method

const widget = document.createElement("feedback-widget");
widget.configure({
  proxyUrl: "https://your-backend.example.com",
  clientKey: "fwk_xxxxxxxxxxxxxxxxx",
  repo: "owner/repo",
  projectName: "My App",
  placement: "bottom-left",
  labels: ["feedback"],
  theme: {
    primaryColor: "#8b5cf6",
    backgroundColor: "#ffffff",
    textColor: "#1f2937",
    borderRadius: "12px",
  },
});
document.body.appendChild(widget);

Configuration

Widget options

| Option | Type | Required | Default | Description | | ------------- | --------------------------------- | -------- | ---------------- | ----------------------------------------- | | proxyUrl | string | Yes | — | URL of the backend proxy | | clientKey | string | No* | — | Key field sent as X-Feedback-Client-Key | | repo | string | Yes | — | Target GitHub repo in owner/repo format | | projectName | string | No | — | Label shown in issue metadata | | placement | 'bottom-right' \| 'bottom-left' | No | 'bottom-right' | Default anchor before user drag overrides | | labels | string[] | No | [] | Default labels applied to created issues | | theme | Partial<FeedbackTheme> | No | See below | Visual customization |

* clientKey is required once backend legacy fallback is disabled.

Users can drag the widget (launcher or toolbar area), and the last dragged position is saved in localStorage per repo.

Theme defaults

| Property | Default | | ----------------- | --------- | | primaryColor | #3b82f6 | | backgroundColor | #ffffff | | textColor | #1f2937 | | borderRadius | 8px |

License

MIT