Web SDK theming

The widget ships its own stylesheet and keeps it to itself: every rule it emits is scoped to [data-runbear], the attribute on the widget's own element. It declares nothing on your :root and doesn't restyle your application. You restyle the widget with CSS variables, and target its parts through stable class and data hooks.

This page describes 0.3.0 and later. If you are upgrading from 0.2.x, see Migrating from 0.2.x.

CSS variables#

Set any of these on any ancestor of the widget, including :root, and the widget picks them up. The names below are the public contract; variables not listed here are internal and may change in any release.

Chart colours come only from these variables, never from the agent: a chart's series take --runbear-chart-1 to --runbear-chart-4 in order.

:root {
  --runbear-primary: 221 83% 53%;
  --runbear-primary-foreground: 0 0% 100%;
  --runbear-radius: 0.75rem;
}

Dark mode#

Dark mode is off unless you ask for it. There are three ways, in the order most sites want them:

1. Follow your app's theme switch. Put class="dark" on <html>, <body>, or any ancestor of the widget.
2. Switch one widget only. Add the class to the widget element itself: document.getElementById("runbear-chat-container").classList.add("dark").
3. Follow the operating system. Add data-runbear-theme="auto" to the widget or any ancestor, and the widget follows prefers-color-scheme. This is opt-in, so a site with its own light and dark control never has the widget disagree with it.

A --runbear-* value you set applies to both palettes. To differ per theme, scope the override the same way you turned dark mode on:

:root { --runbear-primary: 221 83% 53%; }
.dark { --runbear-primary: 213 94% 68%; }

or, with data-runbear-theme="auto":

:root { --runbear-primary: 221 83% 53%; }

@media (prefers-color-scheme: dark) {
  [data-runbear-theme="auto"] { --runbear-primary: 213 94% 68%; }
}

Class and data hooks#

These names are stable and safe to target from your own CSS.

The widget

Response components (0.3.0 and later; the card hooks from 0.4.0; the image, link, pager, list, table and chart hooks from 0.6.0)

An inert option button carries aria-disabled="true", not the disabled attribute, so it stays focusable and readable. Style it with [aria-disabled="true"], not :disabled.

Overriding a rule#

Utility classes the SDK generates apply to the descendants of the widget's outer element. Nothing the SDK emits uses !important, and its rules have the specificity of one attribute plus one class.

The SDK's stylesheet is appended to <head> when the module is imported, so it is the last sheet in the document and wins every tie. To override a rule, be more specific: #runbear-chat-container .runbear-suggestions button { … } overrides; a bare .runbear-suggestions button { … } doesn't. The --runbear-* variables need none of this: the widget reads them from your side of the cascade, so they always apply.

The only rules that reach outside the widget are two that set Tailwind's private --tw-* custom properties on every element. They affect nothing but Tailwind's own internals.

Migrating from 0.2.x#

0.3.0 isolated the widget's styles, which is a breaking change for any site that themed it:

• The theme variables moved from :root to the widget element and were renamed from --background, --primary and the rest to the --runbear-* names above. Rename your overrides: --primary becomes --runbear-primary, and so on.
• --popover*, --card* and --chart-* were removed.
• The widget no longer restyles the rest of your page, so anything on your page that relied on the SDK's variables needs its own.

Related#

• Install: the CSP requirement
• Response components: what the component hooks style
• Configuration: assistant name and avatar