Theme Mode

The iFrame supports dynamic switching between light and dark modes. Only those two values are valid.

Theme state lives on your side. When your site’s theme changes you notify the iFrame, and the iFrame applies it.

Telling the iFrame the theme changed

import integration from "services/integration";
 
// Toggle between light and dark, and notify the iframe
integration.helpers.toggleThemeMode();
 
// Or set a specific mode
integration.helpers.toggleThemeMode("dark");

The helper sends theme-mode-change, and additionally stores the choice and sets data-theme on your document.body — so your own styling can key off the same attribute.

Reading the current mode

getCurrentThemeMode() reads prefers-color-scheme from your site’s Local Storage and returns it as-is — so it returns null, not a mode, until a theme has been set at least once. Treat a falsy result as “no preference yet” rather than as light mode:

const mode = helpers.getCurrentThemeMode() ?? "dark";

The mode the iFrame actually applies when nothing is stored is dark, from the module’s THEME_MODE.DEFAULT. See Initial theme on load for the full fallback order.

import integration from "services/integration";
 
import { helpers } from "./integration";
 
const [mode, setMode] = useState(helpers.getCurrentThemeMode());
 
const handleChange = () => {
  helpers.toggleThemeMode();
};

Initial theme on load

The iFrame sends sdkInit once it has finished loading. Its payload may carry defaultThemeMode — the mode configured for your brand:

{
  type: 'sdkInit',
  value: {
    defaultThemeMode: 'light', // or 'dark'
  },
}

Treat it as a fallback, not an override: apply it only when the player has no stored preference of their own. The integration module resolves the mode in this order:

1. prefers-color-scheme from your site’s Local Storage, if set.
2. defaultThemeMode from the sdkInit payload, if the iFrame sent one.
3. dark, the module’s built-in default.

import integration from "services/integration";
 
integration.on("sdkInit", ({ value }) => {
  const stored = localStorage.getItem("prefers-color-scheme");
  integration.helpers.toggleThemeMode(stored || value?.defaultThemeMode);
});

Note that the sdkInit payload is nested under value. Other incoming events are flat — see Message envelope.