Light & Dark Theme

If your website switches between a light and a dark design, the widget can switch with it. You set up a second color set for dark mode in the dashboard, and the SDK picks the right one on your site.

1. Set up the dark colors

In the dashboard, open your agent → Playground. Switch the style panel to Dark, turn on Use a dark theme and pick the colors. Name, logo, font and texts stay the same in both themes, only colors differ.

Without a dark theme the widget always uses its normal colors, whatever you configure below.

2. Let the widget follow your site

Nothing to do: the default is theme: "auto". The widget checks your page in this order and uses the first match:

  1. A theme class on <html> or <body>: dark, dark-mode, dark-theme, theme-dark (or the light versions)
  2. A theme attribute on <html> or <body>: data-theme, data-color-scheme, data-color-mode, data-mode or data-bs-theme with a value containing dark or light
  3. The background color of <body> or <html>
  4. A declared color scheme (color-scheme in CSS or <meta name="color-scheme">). If you declare both light dark, the visitor's system setting decides.

Pages without any of these count as light. That way a light-only website never shows a dark widget just because a visitor's computer is in dark mode.

The widget watches <html> and <body> for changes, so a theme toggle on your site switches an open chat right away. Common setups like next-themes, Tailwind's dark class, Bootstrap's data-bs-theme and most WordPress dark mode plugins work without extra code.

3. Or set the theme yourself

Use this if your site marks dark mode somewhere else, for example on a wrapper element, or if you want a fixed theme.

Fixed theme

<script
  async
  src="https://unpkg.com/@bitpalm/ai-agents"
  data-slug="your-agent-slug"
  data-theme="dark"
></script>
<BitPalmAgent slug="your-agent-slug" theme="dark" />
const widget = createWidget({ slug: "your-agent-slug", theme: "dark" });

Switch at runtime

widget.setTheme("dark");  // or "light"
widget.setTheme("auto");  // follow the website again

With the script tag or the React component, dispatch a browser event from your theme toggle:

window.dispatchEvent(
  new CustomEvent("bitpalm-theme", {
    detail: { slug: "your-agent-slug", theme: "dark" },
  })
);

For the React component, changing the theme prop works too.

Standalone chat page

The fullpage chat at /t/your-agent-slug/chat follows the visitor's system setting. Add ?theme=dark or ?theme=light to the link to fix it.