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: light theme -->
<rai-channel-widget
  widget-id="YOUR_WIDGET_ID"
  theme="light"
  api-url="YOUR_API_URL"
  widget-url="YOUR_WIDGET_URL"
></rai-channel-widget>

<!-- Widget SDK: dark theme -->
<rai-channel-widget
  widget-id="YOUR_WIDGET_ID"
  theme="dark"
  api-url="YOUR_API_URL"
  widget-url="YOUR_WIDGET_URL"
></rai-channel-widget>

For iframe embeds, append the theme as a query parameter:

<!-- Iframe: dark theme -->
<iframe
  src="https://prod-widgets.returning.ai/channel/YOUR_WIDGET_ID?theme=dark"
  style="width: 100%; height: 600px; border: none;"
></iframe>

CSS Custom Properties

The Widget SDK renders inside a Shadow DOM, which isolates widget styles from your page. However, widgets expose CSS custom properties (variables) that you can set on the host element to customize colors and spacing.

custom-theme.css

/* Override widget custom properties from your stylesheet */
rai-channel-widget {
  --rai-primary: #277BFF;
  --rai-primary-hover: #1a6ae6;
  --rai-border-radius: 12px;
  --rai-font-family: 'Inter', sans-serif;
}

Shadow DOM isolation

Your page's CSS will not leak into the widget, and the widget's CSS will not affect your page. CSS custom properties are the intentional bridge for theming.

Locale & Language

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

<rai-channel-widget
  widget-id="YOUR_WIDGET_ID"
  theme="dark"
  locale="ar"
  api-url="YOUR_API_URL"
  widget-url="YOUR_WIDGET_URL"
></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
  widget-id="YOUR_WIDGET_ID"
  width="100%"
  height="800px"
  api-url="YOUR_API_URL"
  widget-url="YOUR_WIDGET_URL"
></rai-channel-widget>

<!-- Fixed dimensions -->
<rai-channel-widget
  widget-id="YOUR_WIDGET_ID"
  width="400px"
  height="500px"
  api-url="YOUR_API_URL"
  widget-url="YOUR_WIDGET_URL"
></rai-channel-widget>

For iframe embeds, control sizing via CSS on the iframe element or its container. 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.