Iframe Theming
Chastify supplies theme information to both runtime and setup iframes. Apply those values to your page and its controls instead of assuming a dark background.
Treat ui.bg, ui.text, and ui.border as the starting colors. ui.isDark is the host's light/dark styling hint, not a measured contrast score. Custom themes still need visual checks for your panels, muted text, and badges.
Theme Payload
The launch URL fragment contains URI-encoded JSON. A runtime payload includes:
{
"bridge": {
"v": 1,
"nonce": "current-launch-nonce",
"parentOrigin": "https://chastify.net"
},
"sessionId": "extension-session-id",
"lockId": "lock-id",
"ui": {
"isDark": true,
"bg": "rgb(10, 10, 10)",
"text": "#e5e7eb",
"border": "#27272a"
}
}
Setup also receives ui in its launch payload and in chastify:ext:setup:init under context.ui. Setup does not need a runtime session ID to apply a theme.
| Field | Meaning |
|---|---|
ui.isDark | Host styling hint for choosing light/dark surface variants. |
ui.bg | CSS background value sampled from the host surface. The host can flatten translucent backgrounds or gradients for the iframe. |
ui.text | Primary text color. |
ui.border | Border color. |
ui.bg can contain a complete CSS background value. Assign it to background; do not assume it is a hex color or put it into backgroundColor. Use an opaque fallback if the supplied background is empty or transparent.
Parse The Hash
The sample project provides parseHashPayload, themeVars, and the UiSkinV1 type in apps/extension/src/lib/ChastifyBridge.ts. Reuse that file in the sample project or copy/adapt it into your own project; it is not an installed SDK package.
import { parseHashPayload, themeVars } from "../lib/ChastifyBridge";
const payload = parseHashPayload();
const vars = themeVars(payload?.ui ?? null);
The parser decodes the fragment and returns null when it cannot parse it. themeVars preserves usable host colors, provides an opaque background fallback, and derives panel, muted, and inputBg. If isDark is missing, it uses the browser's preferred color scheme when available.
A theme fallback can help a standalone design preview. It does not create bridge authorization; runtime requests still need a valid launch. See Iframe Quickstart.
Minimal CSS Variables
Apply tokens at startup and call the same function again after a validated theme update:
import { parseHashPayload, themeVars, type UiSkinV1 } from "../lib/ChastifyBridge";
const payload = parseHashPayload();
function applyTheme(ui?: UiSkinV1 | null) {
const vars = themeVars(ui);
const root = document.documentElement;
root.style.setProperty("--chastify-bg", vars.pageBg);
root.style.setProperty("--chastify-text", vars.text);
root.style.setProperty("--chastify-border", vars.border);
root.style.setProperty("--chastify-panel", vars.panel);
root.style.setProperty("--chastify-muted", vars.muted);
root.style.setProperty("--chastify-input", vars.inputBg);
root.style.colorScheme = vars.isDark ? "dark" : "light";
root.dataset.themeMode = vars.isDark ? "dark" : "light";
}
applyTheme(payload?.ui);
html, body, #root {
margin: 0;
}
body {
background: var(--chastify-bg);
color: var(--chastify-text);
}
.panel {
background: var(--chastify-panel);
border: 1px solid var(--chastify-border);
padding: 1rem;
}
.muted { color: var(--chastify-muted); }
input, textarea, select {
color: var(--chastify-text);
background: var(--chastify-input);
border: 1px solid var(--chastify-border);
}
color-scheme helps native browser controls use the intended light/dark appearance. Check select options, placeholders, disabled controls, and focus indicators separately. Avoid setting the observed content to an ever-growing viewport minimum when using the resize helper.
React Example
Keep the current ui in state. Recomputing from an unchanged initial payload will not apply a live theme message.
import { useEffect, useState } from "react";
import { themeVars, type IframeHashPayload, type UiSkinV1 } from "../lib/ChastifyBridge";
export function ExtensionApp({ payload }: { payload: IframeHashPayload }) {
const [ui, setUi] = useState<UiSkinV1 | null>(payload.ui ?? null);
const vars = themeVars(ui);
const parentOrigin = payload.bridge?.parentOrigin;
const nonce = payload.bridge?.nonce;
useEffect(() => {
if (!parentOrigin || !nonce) return;
const onMessage = (event: MessageEvent) => {
if (event.source !== window.parent || event.origin !== parentOrigin) return;
const msg = event.data;
if (msg?.type !== "chastify:ext:ui" || msg.v !== 1 || msg.nonce !== nonce) return;
if (msg.ui && typeof msg.ui === "object") setUi(msg.ui);
};
window.addEventListener("message", onMessage);
return () => window.removeEventListener("message", onMessage);
}, [parentOrigin, nonce]);
return (
<main style={{ background: vars.pageBg, color: vars.text,
colorScheme: vars.isDark ? "dark" : "light", padding: 16 }}>
<section style={{ background: vars.panel, border: `1px solid ${vars.border}`, padding: 16 }}>
<h1>My Extension</h1>
<p style={{ color: vars.muted }}>Session information appears here.</p>
<label>
Display name
<input style={{ background: vars.inputBg, color: vars.text,
border: `1px solid ${vars.border}` }} />
</label>
</section>
</main>
);
}
Create a fresh component for a new iframe launch. If your own shell reuses the component across different launch payloads, reset its theme state for that new context as well.
Tailwind Pattern
When using Tailwind, select explicit light/dark variants from the current theme state. The host's dark-mode class is outside your iframe and is not automatically inherited by it.
const vars = themeVars(ui);
const panelClass = vars.isDark
? "border-white/10 bg-black/30 text-slate-100"
: "border-slate-200 bg-white/85 text-slate-950 shadow-sm";
const successClass = vars.isDark
? "border-emerald-300/20 bg-emerald-400/10 text-emerald-100"
: "border-emerald-500/25 bg-emerald-50 text-emerald-950";
const errorClass = vars.isDark
? "border-rose-300/20 bg-rose-400/10 text-rose-100"
: "border-rose-500/25 bg-rose-50 text-rose-950";
Use the selected class on the surface that contains the text. Include a visible status label or icon so color alone does not communicate success or failure. These are example palettes, not a guarantee of contrast against every custom background.
Live Theme Updates
Both runtime and setup can receive:
type UiUpdateMessage = {
type: "chastify:ext:ui";
v: 1;
nonce: string;
ui: { isDark?: boolean; bg?: string; text?: string; border?: string };
};
For a non-React page using applyTheme above, register this listener after validating the launch payload. It uses that payload's nonce and parentOrigin:
const nonce = payload?.bridge?.nonce;
const parentOrigin = payload?.bridge?.parentOrigin;
function onThemeMessage(event: MessageEvent) {
if (!nonce || !parentOrigin) return;
if (event.source !== window.parent || event.origin !== parentOrigin) return;
const msg = event.data;
if (msg?.type !== "chastify:ext:ui" || msg.v !== 1 || msg.nonce !== nonce) return;
if (msg.ui && typeof msg.ui === "object") applyTheme(msg.ui);
}
window.addEventListener("message", onThemeMessage);
// When your page/view is disposed:
// window.removeEventListener("message", onThemeMessage);
Handle the startup payload as well as live messages. The parent can reload or remount an iframe when launch context changes; do not rely exclusively on one live update event. Use the resize helper when theme changes affect content height.
Common Mistakes
- Hardcoding pale text inside a panel with no light-theme alternative.
- Styling only the outer page and forgetting cards, badges, inputs, and result messages.
- Treating
ui.bgas a hex color or assigning a gradient tobackgroundColor. - Memoizing the first theme forever instead of applying updates.
- Accepting a theme message without checking its source window, origin, protocol version, and current nonce.
- Leaving message listeners active after a view is disposed.
- Assuming
isDarkproves every custom color combination has enough contrast.
Do not use theme values for authorization, session identity, unlock conditions, rewards, or punishments. Those decisions belong to the relevant server API and its permission checks.
Checklist
Before release, check runtime and setup in light, dark, and an available custom theme. Inspect readable text, native controls, links, focus indicators, disabled states, and success/error messages. Test a narrow screen, a live theme change, and collapsing content after it expands.
Continue with Iframe Quickstart, API Examples, or Extension Release & Beta Testing.