Theming & Customization

Make Returning.AI widgets match your brand. Control the color scheme, language, and sizing to create a seamless experience for your users.

Theme Attribute

All widgets support a theme attribute that switches between light and dark color schemes.

Value	Description
"light"	Light background with dark text. Default value.
"dark"	Dark background with light text. Best for dark-themed platforms and trading dashboards.

theme-examples.html

<!-- Widget SDK (bundle mode, recommended): dark theme -->
<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  theme="dark"
  embed-token="TOKEN_FROM_YOUR_SERVER"
  bundle-url="https://prod-widgets.returning.ai/channel-widget/bundle/widget.js"
></rai-channel-widget>

<!-- Widget SDK (iframe mode): light theme -->
<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  theme="light"
  embed-token="TOKEN_FROM_YOUR_SERVER"
></rai-channel-widget>

For embed scripts, set the theme as a data-theme attribute:

<!-- Embed Script: dark theme -->
<script
  src="https://prod-widgets.returning.ai/widget-loader.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-widget-type="custom"
  data-container="returning-ai-widget-YOUR_WIDGET_ID"
  data-theme="dark"
  data-api-url="https://prod-widgets.returning.ai"
  data-widget-url="https://prod-widgets.returning.ai/custom-widget"
></script>

CSS Custom Properties

Widgets expose CSS custom properties (variables) that you can set on the host element to customize colors and spacing. These work in both rendering modes - in bundle mode your page CSS cascades into the widget directly, and in iframe mode they cross the Shadow DOM boundary as the intentional theming bridge.

custom-theme.css

/* Override widget custom properties from your stylesheet */
rai-channel-widget {
  --rai-accent: #E85A1E;       /* Primary accent color */
  --rai-text4: #475569;        /* Quaternary text color */
  --rai-loader-bg: #f1f5f9;   /* Loading state background */
  --rai-error-bg: #fef2f2;    /* Error state background */
}

CSS behavior depends on rendering mode

In iframe mode (default), your page's CSS will not leak into the widget thanks to Shadow DOM isolation. CSS custom properties are the intentional bridge for theming.

In bundle mode (when bundle-url is set), the widget renders in the light DOM and your page CSS cascades into the widget naturally. This gives you more styling control but means you should test for CSS conflicts.

Locale & Language

Use the locale attribute to control the language and number formatting within the widget. The default locale is en.

<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  theme="dark"
  locale="ar"
  embed-token="TOKEN_FROM_YOUR_SERVER"
  bundle-url="https://prod-widgets.returning.ai/channel-widget/bundle/widget.js"
></rai-channel-widget>

Container Sizing

Widgets accept width and height attributes. Both accept any valid CSS value.

Attribute	Default	Description
width	"100%"	Width of the widget container. Fills parent by default.
height	"600px"	Height of the widget container.

<!-- Full-width, custom height -->
<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  width="100%"
  height="800px"
  embed-token="TOKEN_FROM_YOUR_SERVER"
></rai-channel-widget>

<!-- Fixed dimensions -->
<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  width="400px"
  height="500px"
  embed-token="TOKEN_FROM_YOUR_SERVER"
></rai-channel-widget>

For embed scripts, control sizing via data-width and data-height attributes. The widget content will fill the available space.

Best Practices

•Match your site's theme. If your platform uses a dark mode, set theme="dark" on the widget. Detect theme changes dynamically and update the attribute accordingly.
•Test both light and dark. Always preview your widget in both themes to ensure text contrast and brand colors work well in each mode.
•Use responsive widths. Set width="100%" and let the parent container control the max width. This ensures the widget adapts to mobile and desktop layouts.
•Set an appropriate height. Different widget types have different ideal heights. Stores and channels work best at 600-700px, while currency widgets can be shorter at 400px.
•Set the locale early. The locale attribute affects text rendering and number formatting. Set it on initial render to avoid a flash of untranslated content.