Widget Configuration

The BugPin widget is a lightweight, embeddable feedback button that can be fully customized to match your brand. This reference covers all configuration options: button position, shape, colors for light and dark mode, tooltip, hover effects, feature toggles (screenshot, annotation, console capture), and screenshot settings.

Deployment Requirements

HTTPS Requirement

Both your BugPin server and websites embedding the widget must use HTTPS. Browsers block HTTP scripts on HTTPS sites (mixed content blocking).

Requirements:

Valid SSL/TLS certificate on BugPin server
HTTPS enabled on your website
Use a reverse proxy (Nginx, Traefik, Caddy) for SSL termination

See Reverse Proxy Setup for configuration details.

CORS Headers

BugPin automatically configures CORS headers to allow the widget to be embedded on any website:

Access-Control-Allow-Origin: * - Allows requests from any origin
Cross-Origin-Resource-Policy: cross-origin - Allows cross-origin loading

No configuration needed - these headers are set automatically.

Reverse Proxy Configuration

Ensure your reverse proxy doesn't strip or override these CORS headers. See Reverse Proxy Setup for details.

Domain Whitelisting

For production deployments, configure domain whitelisting to restrict which websites can use your widget:

Go to Projects → Select project
Navigate to Settings → Security
Add allowed domains (e.g., example.com)
Subdomain support: example.com allows example.com and *.example.com

When enabled, the widget only accepts bug reports from whitelisted domains. Other domains receive 403 FORBIDDEN.

Security Recommendation

Enable domain whitelisting for production projects to prevent unauthorized usage.

Configuration Methods

Widget settings can be configured in three ways (in order of priority):

Script data attributes - Highest priority, set in HTML
Admin panel - Configure in project settings
Default values - Built-in defaults

Position

Control where the widget button appears on the screen.

Value	Description
`bottom-right`	Bottom right corner (default)
`bottom-left`	Bottom left corner
`top-right`	Top right corner
`top-left`	Top left corner

<script
  src="https://bugs.example.com/widget.js"
  data-api-key="your-project-api-key"
  data-position="bottom-left"
  async
></script>

Button Appearance

Button Shape

Value	Description
`round`	Circular button (default)
`rectangle`	Rectangular button

Button Text

Set custom text to display on the button. If not set, only the icon is shown.

Button Icon

Choose from available icons or use the default bug icon. The icon is displayed alongside any button text.

Icon Customization

Option	Default	Description
`buttonIconSize`	`18`	Icon size in pixels
`buttonIconStroke`	`2`	Icon stroke width

Theme

The widget supports light and dark modes with automatic detection.

Value	Description
`auto`	Automatically detect from website's theme (default)
`light`	Always use light mode
`dark`	Always use dark mode

<script
  src="https://bugs.example.com/widget.js"
  data-api-key="your-project-api-key"
  data-theme="dark"
  async
></script>

In auto mode, the widget detects the host page's theme by checking CSS classes (e.g., class="dark"), data attributes (e.g., data-theme="dark"), background color luminance, and the OS prefers-color-scheme preference. It updates in real-time when the page theme changes.

Manual Theme Override

If auto-detection doesn't work for your site, you can force a specific theme with data-bugpin-theme:

<script
  src="https://bugs.example.com/widget.js"
  data-api-key="your-project-api-key"
  data-bugpin-theme="dark"
  async
></script>

This overrides auto-detection without changing the base theme mode. See Widget Theming for full details.

Colors

Customize colors for both light and dark modes. All colors should be valid CSS color values (hex, rgb, etc.).

Launcher Button Colors (Light Mode)

Option	Default	Description
`lightButtonColor`	`#02658D`	Button background color
`lightTextColor`	`#ffffff`	Button text/icon color
`lightButtonHoverColor`	`#024F6F`	Button background on hover
`lightTextHoverColor`	`#ffffff`	Text/icon color on hover

Launcher Button Colors (Dark Mode)

Option	Default	Description
`darkButtonColor`	`#02658D`	Button background color
`darkTextColor`	`#ffffff`	Button text/icon color
`darkButtonHoverColor`	`#036F9B`	Button background on hover
`darkTextHoverColor`	`#ffffff`	Text/icon color on hover

Dialog Colors

The dialog (popup) has separate settings for button colors and surface colors.

Light Mode Button Colors:

Option	Default	Description
`dialogLightButtonColor`	`#02658D`	Dialog button background
`dialogLightTextColor`	`#ffffff`	Dialog button text
`dialogLightButtonHoverColor`	`#024F6F`	Dialog button hover background
`dialogLightTextHoverColor`	`#ffffff`	Dialog button hover text

Dark Mode Button Colors:

Option	Default	Description
`dialogDarkButtonColor`	`#02658D`	Dialog button background
`dialogDarkTextColor`	`#ffffff`	Dialog button text
`dialogDarkButtonHoverColor`	`#036F9B`	Dialog button hover background
`dialogDarkTextHoverColor`	`#ffffff`	Dialog button hover text

Dialog Surface Colors

Customize the dialog's background, input fields, and text for each mode. These settings are available in the Admin Console under Widget → Dialog.

Light Mode Surface Colors:

Option	Default	Description
`dialogLightBackgroundColor`	`#ffffff`	Dialog background
`dialogLightSecondaryColor`	`#f5f5f5`	Tab bar, muted element backgrounds
`dialogLightInputColor`	`#ffffff`	Input, textarea, select backgrounds
`dialogLightForegroundColor`	`#0a0a0a`	All dialog text

Dark Mode Surface Colors:

Option	Default	Description
`dialogDarkBackgroundColor`	`#0a0a0a`	Dialog background
`dialogDarkSecondaryColor`	`#262626`	Tab bar, muted element backgrounds
`dialogDarkInputColor`	`#1a1a1a`	Input, textarea, select backgrounds
`dialogDarkForegroundColor`	`#fafafa`	All dialog text

See Widget Theming for a detailed guide on customizing the widget's appearance.

Language

The widget and reporter emails are translated into 8 languages: English, German, French, Dutch, Spanish, Italian, Japanese, and Simplified Chinese.

Each project chooses one of two modes under Widget → Language in the Admin Console:

Mode	Behavior
Auto	Pick a language from the host page's `<html lang>` attribute or the visitor's browser. Falls back to English if no supported match is found.
Manual	Lock the widget to one language regardless of the visitor's browser.

Host pages can also pass data-language="de" on the script tag or language: 'de' to BugPin.init() to override the project default (Auto mode only). See Widget Translations for the full reference, supported locale codes, and runtime API (BugPin.setLanguage() / BugPin.getLanguage()).

Show a tooltip when users hover over the widget button. Tooltip text supports per-locale overrides under Widget → Button in the Admin Console.

Option	Default	Description
`tooltipEnabled`	`false`	Show tooltip on hover
`tooltipText`	`null`	Custom tooltip text

Hover Effects

Option	Default	Description
`enableHoverScaleEffect`	`true`	Scale button slightly on hover

Feature Toggles

Enable or disable specific widget features.

Option	Default	Description
`enableScreenshot`	`true`	Allow screenshot capture
`enableAnnotation`	`true`	Allow screenshot annotation
`enableConsoleCapture`	`true`	Capture browser console logs

Screenshot Settings

Capture Method

Value	Description
`visible`	Capture only the visible viewport (default)
`fullpage`	Capture the entire scrollable page
`element`	Capture a specific element

Screen Capture API

Option	Default	Description
`useScreenCaptureAPI`	`false`	Use browser's Screen Capture API

The Screen Capture API uses the browser's native screen sharing to capture pixel-perfect screenshots. Unlike the default DOM-based capture, it renders exactly what the user sees — including canvas elements, WebGL, iframes, and CSS effects that DOM serialization may miss.

When enabled, the user is prompted to share their screen before each capture. A consent dialog is shown on first use to explain what will happen.

Requirements

The Screen Capture API has specific requirements that must be met for it to work:

HTTPS — The host page must be served over HTTPS (or localhost for development)
Browser support — Chrome 72+, Edge 79+, Firefox 66+, Safari 13+ (partial)
macOS Screen Recording permission — On macOS, the browser must have Screen Recording permission granted in System Settings > Privacy & Security > Screen Recording. Without this, the API will fail silently and fall back to DOM-based capture

macOS Users

If screenshots work but the browser console shows Screen Capture API unavailable, falling back to DOM capture, the browser likely lacks Screen Recording permission at the OS level. Grant the permission and restart the browser.

Fallback Behavior

If the Screen Capture API fails for any reason (permission denied, unsupported browser, missing OS permission), the widget automatically falls back to DOM-based capture using html-to-image. The screenshot will still be taken — only the capture method changes.

Maximum Screenshot Size

Option	Default	Description
`maxScreenshotSize`	`10485760`	Maximum size in bytes (10MB)

Configured in the Admin Console under Widget → Screenshot. If a capture exceeds the limit, the widget's Screenshots tab surfaces a Reduce capture quality toggle. Enabling it re-encodes the capture at a lower JPEG quality so it fits under the limit instead of rejecting the report outright. Only the toggle itself is interactive, the label is not clickable, matching the toggle pattern used elsewhere in the Admin Console.

Validation uses Max. Screenshot Size

Captures are validated against Max. Screenshot Size, not the separate Max. Image Upload Size that applies to user-attached files. The oversize warning in the widget shows the correct limit.

The default for new installs is 10 MB (raised from 5 MB in v1.1.0). Existing installs keep whatever value you previously saved.

Complete Configuration Example

Here's an example using programmatic initialization with all options:

await BugPin.init({
  apiKey: "your-project-api-key",
  serverUrl: "https://bugs.example.com",

  // Position
  position: "bottom-right",

  // Button appearance
  buttonText: "Report Bug",
  buttonShape: "rectangle",
  buttonIcon: "bug",
  buttonIconSize: 18,
  buttonIconStroke: 2,

  // Theme
  theme: "auto",

  // Light mode colors
  lightButtonColor: "#02658D",
  lightTextColor: "#ffffff",
  lightButtonHoverColor: "#024F6F",
  lightTextHoverColor: "#ffffff",

  // Dark mode colors
  darkButtonColor: "#02658D",
  darkTextColor: "#ffffff",
  darkButtonHoverColor: "#036F9B",
  darkTextHoverColor: "#ffffff",

  // Dialog button colors (light mode)
  dialogLightButtonColor: "#02658D",
  dialogLightTextColor: "#ffffff",
  dialogLightButtonHoverColor: "#024F6F",
  dialogLightTextHoverColor: "#ffffff",

  // Dialog surface colors (light mode)
  dialogLightBackgroundColor: "#ffffff",
  dialogLightSecondaryColor: "#f5f5f5",
  dialogLightInputColor: "#ffffff",
  dialogLightForegroundColor: "#0a0a0a",

  // Dialog button colors (dark mode)
  dialogDarkButtonColor: "#02658D",
  dialogDarkTextColor: "#ffffff",
  dialogDarkButtonHoverColor: "#036F9B",
  dialogDarkTextHoverColor: "#ffffff",

  // Dialog surface colors (dark mode)
  dialogDarkBackgroundColor: "#0a0a0a",
  dialogDarkSecondaryColor: "#262626",
  dialogDarkInputColor: "#1a1a1a",
  dialogDarkForegroundColor: "#fafafa",

  // Tooltip
  tooltipEnabled: true,
  tooltipText: "Found a bug?",

  // Effects
  enableHoverScaleEffect: true,

  // Features
  enableScreenshot: true,
  enableAnnotation: true,
  enableConsoleCapture: true,

  // Screenshot settings
  captureMethod: "visible",
  useScreenCaptureAPI: false,
  maxScreenshotSize: 10 * 1024 * 1024,

  // Language (Auto follows the visitor's browser / <html lang>)
  language: "auto",
});

Note: BugPin.init() returns a Promise<void>. It fetches configuration from the server and merges it with the options you provide (your options take priority).

Admin Console Configuration

Most settings can be configured through the Admin Console. Instance-wide defaults live under the Widget group in the sidebar, with one section per area:

Widget → Button — Position, shape, icon, text (per-locale), tooltip (per-locale), launcher colors
Widget → Dialog — Dialog button colors, surface colors, theme overrides
Widget → Screenshot — Capture method, Screen Capture API, max screenshot size
Widget → Language — Auto / Manual mode and default locale

Per-project overrides are available from Projects → select project → Settings, where you can override any of the above settings for a single project.

Settings configured via script data attributes override Admin Console settings.

Deployment Requirements​

HTTPS Requirement​

CORS Headers​

Domain Whitelisting​

Configuration Methods​

Position​

Button Appearance​

Button Shape​

Button Text​

Button Icon​

Icon Customization​

Theme​

Manual Theme Override​

Colors​

Launcher Button Colors (Light Mode)​

Launcher Button Colors (Dark Mode)​

Dialog Colors​

Dialog Surface Colors​

Language​

Tooltip​

Hover Effects​

Feature Toggles​

Screenshot Settings​

Capture Method​

Screen Capture API​

Requirements​

Fallback Behavior​

Maximum Screenshot Size​

Complete Configuration Example​

Admin Console Configuration​