Skip to content

Theming

The platform supports two interface themes: dark and light. Your extension should look correct in both.

How It Works

When createExtHelper() is called, the SDK reads the current theme from the iframe URL and sets the data-theme attribute on the <html> element:

html
<html data-theme="dark">

The value is either dark or light. You can use this attribute to apply theme-specific styles via CSS or read it in JavaScript.

TIP

The platform sets the theme once when the iframe loads. If the user changes the theme, the platform reloads the iframe with the updated value — you don't need to listen for runtime changes.

Using the Theme in CSS

Define CSS variables in :root (dark theme by default) and override them for html[data-theme="light"]:

css
:root {
  --bg-primary: #000000;
  --bg-card: #2a2a2a;
  --text-primary: rgba(248, 248, 248, 0.8);
  --text-heading: #f8f8f8;
}

html[data-theme='light'] {
  --bg-primary: #f5f5f5;
  --bg-card: #ffffff;
  --text-primary: rgba(26, 26, 26, 0.8);
  --text-heading: #1a1a1a;
}

html {
  height: 100%;
  background: var(--bg-primary);
  color: var(--text-primary);
}

.card {
  background: var(--bg-card);
}

h1, h2, h3 {
  color: var(--text-heading);
}

TIP

Set background on <html>, not on <body>. The <html> element stretches to fill the slot container and acts as the background surface. See Slots Layout for details.

The color values above come from the platform's Color System. Using them keeps your extension visually consistent with the rest of the interface.

Reading the Theme in JavaScript

If you need to adjust behavior based on the theme, read the attribute directly:

ts
const theme = document.documentElement.dataset.theme; // 'dark' | 'light'

Design Recommendations

For visual guidelines on supporting themes — contrast, readability, and custom color schemes — see Design Guidelines.