Matching the widget to your app's theme

The widget comes in a light and a dark theme. By default it follows the visitor's operating system. If your app has its own theme toggle, you can make the widget follow that instead — both when the page loads and the moment the user flips the switch.

Set the starting theme

From a script tag:

<script
  src="https://bugdump.com/sdk/latest.js"
  async
  data-api-key="your-api-key"
  data-theme="dark"
></script>

From npm:

Bugdump.init({ apiKey: 'your-api-key', theme: 'dark' });

If your server knows the user's choice — from a cookie or an account setting — render it straight into the tag. The widget then has the right colors on its first paint, before any of your JavaScript runs. An app setting of "system" maps to auto.

Follow your app's theme toggle

The starting theme is read once, when the widget starts. When the user changes theme, call setTheme():

// Script tag: goes through the command queue, so it is safe before the SDK has loaded
bugdump('setTheme', 'dark');

// npm
Bugdump.getInstance()?.setTheme('dark');

It accepts light, dark, or auto. The widget switches immediately, including a panel that is already open, and the screenshot annotation editor uses the new theme the next time it opens.

The script-tag form relies on the three-line window.bugdump stub from the install snippet. On npm, pass the starting theme to init() as well: setTheme() needs an initialized instance, and Bugdump.getInstance()?. simply does nothing until one exists.

React

With @bugdump/react, call setTheme() through the hook, in a component placed once under both your theme provider and BugdumpProvider:

import { useEffect } from 'react';
import { useBugdump } from '@bugdump/react';
import { useTheme } from './theme-provider'; // your app's theme hook

export function BugdumpThemeSync() {
  const bugdump = useBugdump();
  const { theme } = useTheme(); // 'light' | 'dark' | 'system'

  useEffect(() => {
    bugdump?.setTheme(theme === 'system' ? 'auto' : theme);
  }, [bugdump, theme]);

  return null;
}

With bugdump in the dependencies, the theme is set again whenever the widget restarts. Pass the starting theme in the provider's config too, so the widget opens in the right colors.

With the script tag, the same effect calls the command instead: window.bugdump?.('setTheme', theme === 'system' ? 'auto' : theme). With TypeScript, declare the global once:

declare global {
  interface Window {
    bugdump?: (command: string, ...args: unknown[]) => void;
  }
}

Sync the user's setting, not the resolved color. Many theme providers expose both the choice the user made (light, dark, system) and the color currently applied. The applied value is often computed after the first render and can start out as a placeholder, which briefly flashes the widget in the wrong theme on every page load. The setting is correct from the first render.

Pass "system" through as auto instead of resolving it yourself. The widget then follows OS changes on its own, with no extra wiring.

Vue

import { watch } from 'vue';

// theme: a ref holding 'light' | 'dark' | 'system'
watch(
  theme,
  (value) => window.bugdump?.('setTheme', value === 'system' ? 'auto' : value),
  { immediate: true },
);

Plain JavaScript: follow a dark class on <html>

Many sites — including Tailwind's class-based dark mode — switch theme by toggling a dark class on the root element. Mirror it with an observer:

function syncWidgetTheme() {
  const dark = document.documentElement.classList.contains('dark');
  bugdump('setTheme', dark ? 'dark' : 'light');
}

new MutationObserver(syncWidgetTheme).observe(document.documentElement, {
  attributes: true,
  attributeFilter: ['class'],
});
syncWidgetTheme();

Adjust the check if your site marks its theme differently, for example with data-theme on <html> or a class on <body>.

Troubleshooting

The widget ignores the theme passed to init(). A script tag carrying data-api-key has already initialized the widget, and a second init() is ignored. Put the starting theme on the tag as data-theme, and use setTheme() for changes.

The console says Unknown command "setTheme". The page is running an SDK older than 0.0.39 — a cached or self-hosted copy of latest.js, or an older npm version. Update it.

The theme is right on reload but not after toggling. Nothing calls setTheme() when the toggle changes. Hook it to the same state your toggle writes to, as in the examples above.

See also

• Widget configuration reference

• SDK API reference

• Translating and rebranding the widget