JavaScript SDK: Dark mode

The Gleap widget can follow the dark or light mode of your website or web app, with its own colors, logo, header image and composer glow for dark mode.

Dark mode needs the JavaScript SDK v19.0.0 or newer.

Set up dark mode

Open your project in the Gleap dashboard, go to Widget → Look & feel and turn on Adapt to dark / light mode. The widget then has its own settings for each mode. Switch between them with the Light mode and Dark mode tabs:

• Header colors: the colors of the selected header style (Color, Tri-color, or the header color of the Image style).

• UI color: buttons, links and highlights inside the widget.

• Background color: the widget body behind the content.

• Background image: the header image of the Image style.

• Header logo

• Composer glow colors: the glow around the message composer (Agentic v4, with Composer glow turned on).

The header style, its options (Animate, Fade in background, Blur) and the Composer glow switch are shared by both modes. The widget preview shows the mode of the selected tab.

When you turn the option on, the dark mode settings are filled in from your light mode settings: the background becomes dark, the UI color is adjusted so it stays readable on it, and the logo, header image and composer glow are copied over. From then on both modes are independent, and an empty dark mode logo or header image means the widget shows none in dark mode. An automatically generated composer glow is generated again for the dark colors; a custom one is kept as it is.

Generate from light mode in the Dark mode tab fills in the dark mode colors again from the light mode colors (and the header image, for the Image style). If the UI color is hard to see on the background of a mode, the dashboard shows a warning with a readable color you can apply with one click.

While Adapt to dark / light mode is turned off, the widget always uses its normal colors, even if your app requests a color scheme by code. Dark mode also needs dark colors in the dashboard; without them the widget keeps its normal colors.

Automatic detection

With Adapt to dark / light mode turned on, Gleap detects the theme of your page in this order:

1. Theme markers on <html>: the theme attributes data-theme, data-bs-theme, data-color-scheme, data-color-mode, data-mode and data-mui-color-scheme (a value containing dark or light), then the theme classes dark, dark-mode, dark-theme, theme-dark and the light equivalents light, light-mode, light-theme, theme-light.

2. The same theme markers on <body>.

3. The CSS color-scheme property of <html> (only if it is set to either light or dark).

4. The background color of your page.

5. The operating system preference (prefers-color-scheme).

This covers the common theming setups (Tailwind CSS, Bootstrap, MUI, daisyUI, next-themes, …) out of the box. Gleap watches these markers as well as the system preference and switches the widget, the AI chatbar, checklists and notifications as soon as your page changes its theme.

Set the color scheme by code

If your app has its own theme toggle, you can set the color scheme by code. Possible values are "auto" (automatic detection), "light" and "dark". Before the first call, the dashboard setting applies; "auto" makes the widget follow the theme of your page again.

// Follow the theme of your website.
Gleap.setColorScheme("auto");

// Follow your own theme toggle.
Gleap.setColorScheme(isDarkTheme ? "dark" : "light");

// Override the background of dark mode.
Gleap.setColorScheme("dark", {
  darkBackgroundColor: "#121212",
});

The optional lightBackgroundColor and darkBackgroundColor (#rrggbb or #rgb) override the background color of the respective mode. The method can be called before or after Gleap.initialize(), and changes are applied immediately.

setColorScheme only takes effect while Adapt to dark / light mode is turned on in the dashboard.

Dark mode needs dark colors in the dashboard; without them the widget keeps its normal colors. A darkBackgroundColor passed by code is enough on its own.