Web chat widget: light and dark mode

Color mode is on the Web channel settings page (Project settings → Channels → your Web channel), in the Appearance section, under Advanced settings. It has three values: Light, Dark and Match the website.

Color mode defaults to Light. Choosing a different widget style does not change that setting. The widget tells the browser which scheme it is using, so native scrollbars, form fields and autofill inside the chat match the mode instead of being left to the visitor's device.

How "Match the website" decides

It reads your page first, and falls back to the visitor's system setting only when the page says nothing at all. In order:

• A theme declared on <html> or <body>: data-theme, data-color-mode, data-bs-theme or data-color-scheme set to dark or light, or a dark, dark-mode or theme-dark class (and the light equivalents). This is honoured in both directions, so a page that declares light stays light even when the visitor's device is set to dark.
• A CSS color-scheme declaration. color-scheme: dark and color-scheme: only dark both decide; color-scheme: light dark is not a decision and falls through to the next step.
• The page background — the first non-transparent background found on <body>, then <html>. A dark background means dark.
• Only if none of the above applies: the visitor's system setting.

Because almost every real page paints a solid background, the third step usually decides and the system setting is never reached. A white page opens a light widget even for a visitor whose device is in dark mode; that is intended, since a dark widget on a light page reads as broken. Values are matched narrowly, so data-theme="midnight" or data-theme="corporate-dark" is not recognised as a signal and falls through.

The mode is re-checked live. A theme switcher on your own site flips the widget with it, and a change to the visitor's system preference is picked up, with no page reload. If your page wraps light content in a dark shell, the background check can read dark; declare data-theme on <html> to settle it.

The brand colour in dark mode

Brand color (dark) appears in the same Advanced settings block once Color mode is set to Dark or Match the website. Left blank, the widget derives one from your Widget Color: a colour that is genuinely deep is lightened while keeping its hue, and a colour that is already mid-range or bright is used unchanged. A bright blue or green brand therefore looks identical in both modes — that is the expected result, not a fault. If you set a value it has to be a hex colour; anything else is ignored and the derived colour is used. This colour also drives the two shades of the AI Orb, which are recalculated whenever the mode flips.

Overriding the mode from your own site

Two escape hatches, both of which take precedence over the channel setting.

Add data-theme to the embed script. It accepts light, dark or auto:

<script async src="https://chatonio.com/widget/loader.js"
        data-channel-id="YOUR-CHANNEL-ID"
        data-theme="dark"></script>

The attribute is read once when the widget loads, so changing it later has no effect, and if a page carries more than one embed snippet only the last one is read.

Or call chatonio('theme', 'dark') — also 'light' or 'auto' — which repaints straight away. With the initialiser line from Web chat widget: controlling the chat from your site's code in place, a call made before the widget mounts is honoured on the first paint, so there is no flash of the wrong theme. An unrecognised value is ignored with a console message and does not clear an override you set earlier; calling with 'auto' is the only way back to page detection for the rest of that page view.

Under Match the website you can also steer the widget purely from your own markup, by declaring one of the attributes or classes listed above on <html> or <body>. That is what lets a site's own theme switcher drive the widget with no JavaScript integration.

Popups and the captcha panel

On-site popups follow the same colour mode, and so does the captcha panel when one is shown. Any colour you set on a popup campaign is kept in both modes, so a fully designed campaign looks the same in dark mode and only the parts you left unset change. On a page where the widget is excluded by your domain or URL rules, popups still run but always render in light, because the mode is decided by the widget that never loads there.