Widget Theming
The BugPin widget automatically adapts to your website's light or dark mode. It detects the current theme and switches its appearance to match. You can also customize all surface colors for both modes through the Admin Console or force a specific theme via HTML attributes.
Auto-Detection (Default)
When the theme is set to auto (the default), the widget detects your website's current theme using multiple signals, checked in this order:
- Explicit override —
data-bugpin-themeattribute on the script tag (see Manual Override) - CSS classes — Checks
<html>and<body>for common dark mode classes likedark,theme-dark,dark-mode,wp-dark-mode-active - Data attributes — Checks for
data-theme="dark",data-bs-theme="dark",data-color-mode, and similar attributes - CSS
color-schemeproperty — Reads the computedcolor-schemevalue - Background luminance — Analyzes the
<body>background color brightness - OS preference — Falls back to the operating system's
prefers-color-schemesetting
The widget also watches for changes in real-time. When a user toggles your site's dark mode, the widget switches automatically via a MutationObserver on <html> and <body>.
Supported Frameworks
Auto-detection works out of the box with most frameworks and CMS platforms:
| Framework / CMS | Detection Method |
|---|---|
| Tailwind CSS | class="dark" on <html> |
| Bootstrap 5.3+ | data-bs-theme="dark" on <html> |
| DaisyUI | data-theme="dark" on <html> |
| WordPress (WP Dark Mode, DarkMode plugin) | wp-dark-mode-active class or data-wp-dark-mode-active attribute |
| Next.js (next-themes) | class="dark" on <html> |
| Nuxt Color Mode | class="dark-mode" on <html> |
| Custom implementations | Any of the above patterns, or background luminance fallback |
Manual Override
If auto-detection doesn't work for your setup, you can force a specific theme directly on the script tag:
<script
src="https://your-bugpin-server.com/widget.js"
data-api-key="your-project-api-key"
data-bugpin-theme="dark"
async
></script>
| Value | Description |
|---|---|
dark | Force dark mode |
light | Force light mode |
This takes the highest priority and bypasses all auto-detection. Use this when:
- Your site uses a non-standard dark mode implementation
- The widget detects the wrong theme
- You want to guarantee a specific appearance regardless of the host page
data-bugpin-theme overrides auto-detection but does not override the data-theme attribute, which sets the widget's base theme mode (auto, light, or dark). Use data-bugpin-theme when you want auto mode but need to correct its detection.
Customizing Colors
All widget dialog colors can be customized through the Admin Console under Settings > Widget Dialog. Each mode (light and dark) has its own set of color options.
Dialog Surface Colors
These control the overall appearance of the bug report dialog:
Light Mode:
| Setting | Default | Controls |
|---|---|---|
| Background Color | #ffffff | Dialog background |
| Secondary Color | #f5f5f5 | Tab bar, muted element backgrounds |
| Input Field Color | #ffffff | Input, textarea, and select backgrounds |
| Text Color | #0a0a0a | All dialog text (labels, headings, input text) |
Dark Mode:
| Setting | Default | Controls |
|---|---|---|
| Background Color | #0a0a0a | Dialog background |
| Secondary Color | #262626 | Tab bar, muted element backgrounds |
| Input Field Color | #1a1a1a | Input, textarea, and select backgrounds |
| Text Color | #fafafa | All dialog text (labels, headings, input text) |
Dialog Button Colors
These control the Submit and Cancel buttons inside the dialog:
| Setting | Light Default | Dark Default | Controls |
|---|---|---|---|
| Primary Color | #02658D | #02658D | Button background |
| Button Text Color | #ffffff | #ffffff | Button text |
| Primary Color (Hover) | #024F6F | #036F9B | Button background on hover |
| Button Text Color (Hover) | #ffffff | #ffffff | Button text on hover |
Generate Dark Colors from Light
The Admin Console includes a Generate from Light Mode button that automatically creates dark mode colors by inverting your light mode settings. This is a good starting point that you can then fine-tune.
Per-Project Overrides
Colors can be set globally (all projects) or per-project:
- Global — Settings > Widget Dialog
- Per-project — Projects > [Project] > Widget Settings > Enable "Use Custom Settings"
Per-project settings override global settings.
Programmatic Configuration
When using the JavaScript API, you can pass all color options:
await BugPin.init({
apiKey: 'your-project-api-key',
serverUrl: 'https://your-bugpin-server.com',
theme: 'auto',
// Dialog surface colors (light mode)
dialogLightBackgroundColor: '#ffffff',
dialogLightSecondaryColor: '#f5f5f5',
dialogLightInputColor: '#ffffff',
dialogLightForegroundColor: '#0a0a0a',
// Dialog surface colors (dark mode)
dialogDarkBackgroundColor: '#1a1a2e',
dialogDarkSecondaryColor: '#2d2d44',
dialogDarkInputColor: '#252540',
dialogDarkForegroundColor: '#e0e0e0',
// Dialog button colors (light mode)
dialogLightButtonColor: '#02658D',
dialogLightTextColor: '#ffffff',
dialogLightButtonHoverColor: '#024F6F',
dialogLightTextHoverColor: '#ffffff',
// Dialog button colors (dark mode)
dialogDarkButtonColor: '#0e84b1',
dialogDarkTextColor: '#ffffff',
dialogDarkButtonHoverColor: '#02658D',
dialogDarkTextHoverColor: '#ffffff',
});
Troubleshooting
Widget shows wrong theme
If the widget shows light mode when your site is in dark mode (or vice versa):
- Check your dark mode implementation — The widget looks for
class="dark"on<html>or<body>. If your site uses a different pattern, auto-detection may not pick it up. - Use the manual override — Add
data-bugpin-theme="dark"to the script tag. - Check for conflicts — Some CSS frameworks set both
lightanddarkclasses simultaneously. The widget checks for dark classes first.
Widget doesn't switch when toggling theme
The widget watches <html> and <body> for class and attribute changes. If your theme toggle modifies a different element or uses JavaScript variables without changing the DOM, the widget won't detect the change. Solutions:
- Move the dark mode class to
<html>or<body> - Use
data-bugpin-themeas a manual override - Dispatch a custom event to trigger the widget to re-check (coming soon)
Colors look wrong on specific websites
When embedding the widget on a site with unusual background colors, use the Admin Console to customize the dialog surface colors to match. The four surface settings (background, secondary, input, text) give you full control over the dialog's appearance in both modes.