Theming & CSS Variables

Drive the widget's theme from embed config or override the --wx-* CSS variables directly

You can theme the widget from the dashboard (Appearance) or from code. In code, pass a theme object in the embed config or override the --wx-* CSS variables. This page covers the code path.

Theme via Embed Config

Pass a theme (and themeMode) in the config prop or the injected settings:

<WexioWidget
  publicKey="pk_live_..."
  config={{
    theme: {
      light: {
        background: "#ffffff",
        text: "#1a1a1a",
        primary: "#0070f3",
        primaryHover: "#0060df",
        primaryForeground: "#ffffff",
      },
      dark: {
        background: "#0a0a0a",
        text: "#fafafa",
        primary: "#3b82f6",
      },
      radii: { sm: 6, md: 10, lg: 16, xl: 24 },
      launcherPosition: "RIGHT_BOTTOM",
      fontFamily: "'Inter', system-ui, sans-serif",
    },
    themeMode: "auto",
  }}
/>

Every palette key is optional - unset keys fall back to the default for that mode.

Palette to CSS Variable Mapping

The widget exposes its palette as --wx-* custom properties. These are the only supported override surface. There are no component class names to target.

Palette key	CSS variable	Default (light)	Default (dark)
`background`	`--wx-bg`	`#ffffff`	`#121314`
`surface`	`--wx-bg-elevated`	`#f5f5f7`	`#1e1f21`
`surfaceElevated`	`--wx-bg-elevated-2`	`#ebebef`	`#2a2c2e`
`text`	`--wx-fg`	`#121314`	`#f4f4f5`
`textMuted`	`--wx-fg-muted`	`#565d69`	`#a1a1aa`
`textSubtle`	`--wx-fg-subtle`	`#636976`	`#94949e`
`border`	`--wx-border`	`#e4e4e7`	`#2a2c2e`
`borderStrong`	`--wx-border-strong`	`#d1d5db`	`#3f3f46`
`primary`	`--wx-primary`	`#121314`	`#ffffff`
`primaryHover`	`--wx-primary-hover`	`#2a2c2e`	`#e4e4e7`
`primaryForeground`	`--wx-primary-fg`	`#ffffff`	`#121314`
`launcherBackground`	`--wx-launcher-bg`	`#121314`	`#ffffff`
`launcherForeground`	`--wx-launcher-fg`	`#ffffff`	`#121314`
`success`	`--wx-success`	`#10b981`	`#10b981`
`danger`	`--wx-danger`	`#cc1f1f`	`#ef4444`
`homeBackdrop`	`--wx-home-glow`	`#6366f1` (follows `primary` when you set it)	same

homeBackdrop is the glow behind the Home header. Unset, it follows the primary of the same mode. The widget also sets --wx-warning (#f59e0b, the AI-available status dot), which has no palette key.

Radii (theme-invariant)

Key	CSS variable	Default
`sm`	`--wx-radius-sm`	`8px`
`md`	`--wx-radius`	`12px`
`lg`	`--wx-radius-lg`	`20px`
`xl`	`--wx-radius-xl`	`28px`

How Overrides Are Applied

The widget injects your palette as two selector blocks: base values under :root, :host, and dark-mode values under [data-theme="dark"]:

:root, :host {
  --wx-bg: #ffffff;
  --wx-fg: #121314;
  /* … */
  --wx-radius-sm: 8px;
}
[data-theme="dark"] {
  --wx-bg: #121314;
  --wx-fg: #f4f4f5;
  /* … */
}

useThemeMode() always resolves to a concrete light or dark and writes data-theme onto the widget root. For Shadow DOM embeds (React, Web Component) the variables live on the shadow host; for the iframe embed they live on the document.

Theme Mode Resolution

The widget resolves the active mode in this priority order:

A host override: the theme prop or attribute, or window.Wexio("theme", ...). See Install.
A ?theme= URL parameter (dashboard preview links).
A dashboard live-edit message (preview mode only).
The visitor's saved preference (profile, or the cached localStorage value until it loads) - only when the operator allows visitors to change the theme.
The operator's themeMode, when it is light or dark.
The OS prefers-color-scheme.

If you save light or dark explicitly, visitors can't override it. Save auto to let the visitor's system (and the Profile tab toggle) decide.

Launcher Position and Font

launcherPosition: "RIGHT_BOTTOM" | "LEFT_BOTTOM"   // default RIGHT_BOTTOM
fontFamily: "'Inter', system-ui, -apple-system, sans-serif"  // any CSS font stack

Both are theme-invariant. The font stack is written to --wx-font; an unsafe value is dropped and the default font (Geist) applies. For the iframe embed, launcherPosition also flips which side the iframe is pinned to.

Appearance - set the same options in the dashboard.
Reference: Configuration - the full theme shape.
React component - the config prop.