Theming
Theming controls the global appearance of the Website Widget — colors, typography, dark mode, and layout. These settings apply across all components at once. To override styling on individual components, see Component Styles.
Colors
Brand color
The brand color is used for interactive and accent elements such as buttons, links, and active states.
| Parameter | Description | Default Value |
|---|---|---|
data-project-color | The primary brand color for the widget. | "#718096" |
Color palette
The color palette defines base colors for surfaces, text, and borders across the entire widget. These are independent from the brand color.
| Parameter | Description | Default (Light) | Default (Dark) |
|---|---|---|---|
data-surface-color | Base background color for the widget. | "#ffffff" | "#17171a" |
data-surface-elevated-color | Background color for elevated surfaces like cards and inputs. | "#f8f9fa" | "#212124" |
data-surface-hover-color | Background color for hover states. | "#f1f3f5" | "#2a2a2e" |
data-text-color | Primary text color. | "#212529" | "#e4e4e7" |
data-text-muted-color | Secondary/muted text color. | "#868e96" | "#a1a1a9" |
data-border-color | Color for borders and dividers. | "#dee2e6" | "#3f3f45" |
data-anchor-color | Color for links and hyperlinks. | Project color | Project color |
Color scheme
The brand color, color palette, and component styles all support dark mode counterparts by appending -dark to the attribute name (e.g. data-project-color-dark, data-surface-color-dark).
The -dark suffix behaves differently depending on the type of attribute:
- Color palette values are mode-specific.
data-surface-coloronly applies in light mode, anddata-surface-color-darkonly applies in dark mode. If a dark counterpart is not set, the built-in default for that mode is used. This is standard in design systems — a light surface color is inherently a light-mode concept and would look wrong as a dark mode background. - Brand color and component style values apply to both modes by default. Setting
data-project-colorordata-modal-header-background-colorapplies that value in both light and dark mode. The-darksuffix overrides the value in dark mode only.
| Parameter | Description | Default Value |
|---|---|---|
data-color-scheme | Controls whether the widget renders in light or dark mode. Accepts "light", "dark", or "auto" (follows the user's operating system preference). | "light" |
Syncing with host page
If your website already has its own dark mode toggle, you can sync the widget's color scheme with it using data-color-scheme-selector. This removes the need for users to toggle dark mode separately in the widget.
| Parameter | Description | Default Value |
|---|---|---|
data-color-scheme-selector | A CSS selector that, when matching an element on the page, activates dark mode. | Not set |
When set, the widget watches the <html> and <body> elements for changes to the class, data-theme, data-color-mode, and data-bs-theme attributes. Whenever an element matching your selector is found, the widget switches to dark mode. When the selector no longer matches, it switches back to light mode.
When data-color-scheme-selector is set, it takes precedence over data-color-scheme.
Framework examples:
Docusaurus adds data-theme="dark" to <html>:
<script
...
data-color-scheme-selector="[data-theme='dark']"
></script>
Tailwind CSS adds a dark class to <html>:
<script
...
data-color-scheme-selector=".dark"
></script>
Bootstrap adds data-bs-theme="dark" to <html>:
<script
...
data-color-scheme-selector="[data-bs-theme='dark']"
></script>
Per-component dark mode overrides
For example, this gives the modal header a light background in light mode and a dark background in dark mode:
<script
...
data-color-scheme="auto"
data-modal-header-background-color="#f0f0f0"
data-modal-header-background-color-dark="#1a1a1a"
data-modal-header-color="#333333"
data-modal-header-color-dark="#ffffff"
></script>
All supported CSS properties and pseudo-state variants support the -dark suffix.
Example: full light and dark theme
<script
...
data-color-scheme="auto"
data-project-color="#6306B6"
data-project-color-dark="#9d5bd2"
data-surface-color="#ffffff"
data-surface-elevated-color="#f8f9fa"
data-surface-hover-color="#f1f3f5"
data-text-color="#111111"
data-text-muted-color="#666666"
data-border-color="#dee2e6"
data-anchor-color="#2563eb"
data-surface-color-dark="#17171a"
data-surface-elevated-color-dark="#25252a"
data-surface-hover-color-dark="#32323a"
data-text-color-dark="#e4e4e7"
data-text-muted-color-dark="#a1a1aa"
data-border-color-dark="#3f3f45"
data-anchor-color-dark="#60a5fa"
></script>
Typography & scale
| Parameter | Description | Default Value |
|---|---|---|
data-font-family | Sets the font family for all text elements. | "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji" |
data-font-size-xs | Defines font size for extra-small text elements. | "0.75rem" |
data-font-size-sm | Defines font size for small text elements. | "0.875rem" |
data-font-size-md | Defines font size for medium text elements. | "1rem" |
data-font-size-lg | Defines font size for large text elements. | "1.125rem" |
data-font-size-xl | Defines font size for extra-large text elements. | "1.25rem" |
data-scale-factor | Adjusts the scale of all widget elements (font sizes, gaps, paddings, margins). Useful when your site has a non-standard base font size. | "1" |
View modes
The data-view-mode attribute lets you switch between built-in layout modes. A view mode applies a coordinated set of default styles across multiple components, giving you a complete layout with a single attribute. You can still override any individual component style on top of a view mode — user-specified data-* attributes always take precedence over view mode defaults.
| Parameter | Description | Default Value |
|---|---|---|
data-view-mode | The view mode to use. Available values: "default", "sidebar". | "default" |
sidebar
Renders the widget as a persistent right sidebar taking up the full viewport height with a fixed width. This is useful for documentation or support sites where you want the AI assistant to always be visible. See the sidebar style example for a full walkthrough.
The sidebar view mode applies the following defaults:
| Component | Property | Value |
|---|---|---|
| Modal | size | "500px" |
| Modal | lock-scroll | "false" |
| Modal | x-offset | "0" |
| Modal | y-offset | "0" |
| Modal | full-screen-on-mobile | "true" |
| Modal | transition | "slide-left" (300ms) |
| Modal Overlay | hidden | "true" |
| Modal Inner | justify-content | "flex-end" |
| Modal Inner | right | "4px" |
| Modal Inner | bottom | "4px" |
| Modal Inner | top | "4px" |
| Modal Content | border-radius | "var(--mantine-radius-md)" |
| Modal Header | background-color | "#fff" |
| Example Questions | col-span | "12" |
<script
...
data-view-mode="sidebar"
data-modal-open-by-default="true"
data-launcher-button-hidden="true"
></script>