Theming Guide
Customize the ProphetX embed to match your brand — colors, spacing, border radius, font sizes, and light or dark palettes.
What you'll learn
- Use the Theme Playground — visually design a theme and copy the integration snippet.
- Set your brand color — or send a complete light palette.
- Override individual tokens — fine-tune colors, spacing, border radius, and font sizes.
- Update the theme at runtime — react to user preferences or system changes.
Theme Playground
The fastest way to build a theme is the Theme Playground. It gives you a live preview of the embed with your customizations applied in real time.
How it works:
- Open the Theme Playground.
- Use the sidebar to pick an accent color, choose a border radius preset, scale the font sizes, and edit individual color, spacing, radius, and font-size tokens.
- The preview panel updates instantly so you can see how your theme looks across every embed state.
- When you're happy, copy the integration snippet at the bottom of the sidebar. It contains only the values that differ from the default dark theme, ready to paste into your code. A light theme differs from dark in every color, so its snippet is a complete
colorOverridespalette.
TipUse the Theme Playground to test your theme before writing any code. It generates a minimal
EmbedThemeobject that you can drop straight into the SDK setup below.
How theming works
The SDK sends your theme to the embed via postMessage. Inside the embed, a ThemeProvider reads the theme and applies every value as a CSS custom property on the root element. All UI components reference these variables — when a variable changes, the entire embed updates.
You never interact with postMessage directly. The SDK handles it for you. You just pass a theme object. There is no URL parameter for the theme: it only arrives as a PROPHETX_THEME message from your allowed origin, and the embed doesn't validate its values.
Basic theming
The embed always starts from the ProphetX dark palette. The simplest theme sets a primaryColor on top of it:
const THEME = {
primaryColor: '#e91e63',
};| Property | Type | Description |
|---|---|---|
primaryColor | string | Any valid CSS color (hex, rgb, hsl). Sets the primary, primaryHover, cta, and ctaHover tokens to the value you pass. Ignored whenever colorOverrides has any keys — see below. |
primaryColor is enough for a dark integration that only needs your brand color on buttons and links. As soon as you send colorOverrides, the embed uses those instead and primaryColor has no effect, so put primary, primaryHover, cta, and ctaHover inside colorOverrides yourself.
Light or dark
There is no light/dark switch. A theme is a complete palette, and light versus dark is just which colors that palette uses. To render the embed light, send the full light palette in colorOverrides:
const LIGHT_THEME: EmbedTheme = {
colorOverrides: {
primary: "#3ECF8E",
primaryHover: "#2EBF7E",
primaryForeground: "#FFFFFF",
secondary: "#4C526B",
secondaryHover: "#383F5A",
background: "#FFFFFF",
surface: "#F6F8FA",
surfaceElevated: "#FFFFFF",
text: "#24292F",
textMuted: "#57606A",
textSubtle: "#6E7681",
border: "#D0D7DE",
borderSubtle: "#D8DEE4",
error: "#F2586B",
errorBackground: "#fef2f2",
success: "#52CEA6",
successBackground: "#f0fdf4",
warning: "#ca8a04",
warningBackground: "#fefce8",
cta: "#52CEA6",
ctaHover: "#A1E6B6",
ctaForeground: "#0D1117",
filled: "#1A2135",
filledHover: "#2A324A",
filledForeground: "#FFFFFF",
danger: "#F2586B",
dangerHover: "#D94A5C",
dangerForeground: "#FFFFFF",
},
};These are the ProphetX light values. Change any of them to match your brand. The dark palette needs no overrides: an empty theme {} renders it.
SDK integration
Pass the theme prop to ProphetXProvider. The embed applies it on mount and whenever the value changes.
import { useState, useEffect, useCallback } from "react";
import { ProphetXProvider } from "@prophetx/sdk-react";
import type { EmbedTheme } from "@prophetx/sdk-react";
import { App } from "./App";
const THEME: EmbedTheme = {
primaryColor: "#e91e63",
};
export function Root() {
const [token, setToken] = useState<string>();
const refreshToken = useCallback(async () => {
const res = await fetch("/api/prophetx-token");
const { token } = await res.json();
setToken(token);
return token;
}, []);
useEffect(() => { refreshToken() }, [refreshToken]);
return (
<ProphetXProvider
environment="sandbox"
token={token}
theme={THEME}
onSessionExpired={refreshToken}
>
<App />
</ProphetXProvider>
);
}Updating the theme at runtime
You may want to change the theme while the embed is open, for example when a user toggles dark mode in your app. Each SDK handles this differently.
Re-render ProphetXProvider with a new theme value.
The React SDK re-sends an open modal's theme only whenprimaryColororbackgroundColorchanges.A change that only touches the override maps, such as switching between a light and a dark palette, is not sent to a modal that is already open. It applies the next time a flow opens. React Native and JavaScript don't have this limit.
const DARK_THEME: EmbedTheme = {};
// LIGHT_THEME: the full light palette from "Light or dark" above
const [isLight, setIsLight] = useState(false);
return (
<ProphetXProvider
environment="sandbox"
token={token}
theme={isLight ? LIGHT_THEME : DARK_THEME}
onSessionExpired={refreshToken}
>
<button onClick={() => setIsLight((v) => !v)}>Toggle light/dark</button>
<App />
</ProphetXProvider>
);CSS variables reference
Every value in the theme object maps to a CSS custom property set on the embed's root element. The tables below list every variable, its value in the default dark palette and in the ProphetX light palette, and what it controls.
Colors
| Variable | Light palette | Dark (default) | Used for |
|---|---|---|---|
--color-primary | #3ECF8E | #3ECF8E | Primary actions, links |
--color-primary-hover | #2EBF7E | #2EBF7E | Primary hover state |
--color-primary-foreground | #FFFFFF | #0D1117 | Text on primary backgrounds |
--color-primary-background | #ecfdf5 | #022c22 | Selected-state fill (e.g. a chosen payment method) |
--color-secondary | #4C526B | #9196A5 | Secondary actions |
--color-secondary-hover | #383F5A | #ADADB9 | Secondary hover state |
--color-background | #FFFFFF | #0D1117 | Input fields, inset panels |
--color-surface | #F6F8FA | #161B22 | Embed background, cards |
--color-surface-elevated | #FFFFFF | #21262D | Elevated card backgrounds |
--color-text | #24292F | #FFFFFF | Primary text |
--color-text-muted | #57606A | #8B949E | Secondary text |
--color-text-subtle | #6E7681 | #6E7681 | Hint and placeholder text |
--color-border | #D0D7DE | #30363D | Borders, dividers |
--color-border-subtle | #D8DEE4 | #21262D | Subtle dividers |
--color-error | #F2586B | #F2586B | Error text, icons |
--color-error-background | #fef2f2 | #450a0a | Error banner backgrounds |
--color-success | #52CEA6 | #52CEA6 | Success text, icons |
--color-success-background | #f0fdf4 | #052e16 | Success banner backgrounds |
--color-warning | #ca8a04 | #eab308 | Warning text, icons |
--color-warning-background | #fefce8 | #422006 | Warning banner backgrounds |
--color-cta | #52CEA6 | #52CEA6 | Call-to-action button background |
--color-cta-hover | #A1E6B6 | #A1E6B6 | CTA hover state |
--color-cta-foreground | #0D1117 | #0D1117 | Text on CTA buttons |
--color-filled | #1A2135 | #1A2135 | Filled variant button background |
--color-filled-hover | #2A324A | #2A324A | Filled button hover state |
--color-filled-foreground | #FFFFFF | #FFFFFF | Text on filled buttons |
--color-danger | #F2586B | #F2586B | Destructive action button background |
--color-danger-hover | #D94A5C | #D94A5C | Danger hover state |
--color-danger-foreground | #FFFFFF | #FFFFFF | Text on danger buttons |
Spacing
| Variable | Default | Used for |
|---|---|---|
--spacing-xs | 4px | Tight gaps, inline padding |
--spacing-sm | 8px | Small gaps between related elements |
--spacing-md | 16px | Standard padding, section gaps |
--spacing-lg | 24px | Card padding, group spacing |
--spacing-xl | 32px | Section margins, large gaps |
Border radius
| Variable | Default | Used for |
|---|---|---|
--radius-sm | 4px | Inputs, small elements |
--radius-md | 8px | Buttons, badges |
--radius-lg | 12px | Cards, modals |
--radius-full | 9999px | Pills, avatars |
Font size
| Variable | Default | Used for |
|---|---|---|
--font-size-xs | 0.75rem | Captions, fine print |
--font-size-sm | 0.875rem | Secondary text, labels |
--font-size-md | 1rem | Body text |
--font-size-lg | 1.125rem | Subheadings |
--font-size-xl | 1.25rem | Headings |
--font-size-2xl | 1.5rem | Large figures (e.g. the balance) |
Font family
| Variable | Default |
|---|---|
--font-sans | "GT America", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif |
--font-mono | "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace |
NoteFont family is not currently overridable via
ThemePayload."GT America"is named first, but the embed doesn't load the font file, so users see it only if it's installed on their device; everyone else sees the system fallbacks.
Three variables outside the main tables
--color-primary-backgroundand--font-size-2xlare applied when you sendcolorOverrides.primaryBackgroundorfontSizeOverrides["2xl"], but they aren't in the TypeScriptEmbedThemetype yet. In TypeScript, add them with a cast; in JavaScript and Flutter, just include the keys.--color-surface-subtle(#2d333b, used for a few inset panels) is fixed and can't be themed.
Granular overrides
For full control beyond primaryColor, use the override properties. Each one accepts a partial object, so you only include the tokens you want to change. Every token you leave out keeps its dark default.
colorOverrides
colorOverridesOverride any individual color token. Useful when primaryColor isn't enough — for example, matching your brand's error color or surface tones. Because primaryColor is ignored once colorOverrides has keys, set the action colors here too:
const THEME: EmbedTheme = {
colorOverrides: {
primary: "#7c3aed",
primaryHover: "#6d28d9",
cta: "#7c3aed",
ctaHover: "#6d28d9",
ctaForeground: "#ffffff",
surface: "#1a1625",
surfaceElevated: "#2d2640",
border: "#3d3556",
borderSubtle: "#2d2640",
},
};Available keys:
| Key | Maps to CSS variable |
|---|---|
primary | --color-primary |
primaryHover | --color-primary-hover |
primaryForeground | --color-primary-foreground |
secondary | --color-secondary |
secondaryHover | --color-secondary-hover |
background | --color-background |
surface | --color-surface |
surfaceElevated | --color-surface-elevated |
text | --color-text |
textMuted | --color-text-muted |
textSubtle | --color-text-subtle |
border | --color-border |
borderSubtle | --color-border-subtle |
error | --color-error |
errorBackground | --color-error-background |
success | --color-success |
successBackground | --color-success-background |
warning | --color-warning |
warningBackground | --color-warning-background |
cta | --color-cta |
ctaHover | --color-cta-hover |
ctaForeground | --color-cta-foreground |
filled | --color-filled |
filledHover | --color-filled-hover |
filledForeground | --color-filled-foreground |
danger | --color-danger |
dangerHover | --color-danger-hover |
dangerForeground | --color-danger-foreground |
spacingOverrides
spacingOverridesAdjust the spacing scale to match your design system. Values are CSS length strings.
const THEME: EmbedTheme = {
spacingOverrides: {
xs: "0.125rem",
sm: "0.375rem",
md: "0.75rem",
lg: "1.25rem",
xl: "1.75rem",
},
};| Key | Maps to CSS variable | Default |
|---|---|---|
xs | --spacing-xs | 4px |
sm | --spacing-sm | 8px |
md | --spacing-md | 16px |
lg | --spacing-lg | 24px |
xl | --spacing-xl | 32px |
radiusOverrides
radiusOverridesControl how rounded elements appear. Set full to a smaller value for less pill-shaped buttons, or increase sm through lg for a softer feel.
const THEME: EmbedTheme = {
radiusOverrides: {
sm: "0.5rem",
md: "0.75rem",
lg: "1rem",
},
};| Key | Maps to CSS variable | Default |
|---|---|---|
sm | --radius-sm | 4px |
md | --radius-md | 8px |
lg | --radius-lg | 12px |
full | --radius-full | 9999px |
fontSizeOverrides
fontSizeOverridesScale typography up or down. Useful if your app uses a different base font size.
const THEME: EmbedTheme = {
fontSizeOverrides: {
xs: "0.625rem",
sm: "0.75rem",
md: "0.875rem",
lg: "1rem",
xl: "1.125rem",
},
};| Key | Maps to CSS variable | Default |
|---|---|---|
xs | --font-size-xs | 0.75rem |
sm | --font-size-sm | 0.875rem |
md | --font-size-md | 1rem |
lg | --font-size-lg | 1.125rem |
xl | --font-size-xl | 1.25rem |
Full example
Here's a complete dark theme that combines color and radius overrides. Like the Theme Playground's snippet, it lists only what differs from the dark default:
import { useState, useEffect, useCallback } from "react";
import { ProphetXProvider } from "@prophetx/sdk-react";
import type { EmbedTheme } from "@prophetx/sdk-react";
import { App } from "./App";
const THEME: EmbedTheme = {
colorOverrides: {
primary: "#7c3aed",
primaryHover: "#6d28d9",
surface: "#1a1625",
surfaceElevated: "#2d2640",
border: "#3d3556",
cta: "#7c3aed",
ctaHover: "#6d28d9",
},
radiusOverrides: {
sm: "0.5rem",
md: "0.75rem",
lg: "1rem",
},
};
export function Root() {
const [token, setToken] = useState<string>();
const refreshToken = useCallback(async () => {
const res = await fetch("/api/prophetx-token");
const { token } = await res.json();
setToken(token);
return token;
}, []);
useEffect(() => { refreshToken() }, [refreshToken]);
return (
<ProphetXProvider
environment="sandbox"
token={token}
theme={THEME}
onSessionExpired={refreshToken}
>
<App />
</ProphetXProvider>
);
}ThemePayload reference
ThemePayload referenceThe complete type accepted by the SDK's theme prop and updateTheme():
type ThemePayload = {
primaryColor?: string; // ignored when colorOverrides has keys
backgroundColor?: string; // React Native and Flutter only: the native modal's background
colorOverrides?: Partial<{
primary: string;
primaryHover: string;
primaryForeground: string;
secondary: string;
secondaryHover: string;
background: string;
surface: string;
surfaceElevated: string;
text: string;
textMuted: string;
textSubtle: string;
border: string;
borderSubtle: string;
error: string;
errorBackground: string;
success: string;
successBackground: string;
warning: string;
warningBackground: string;
cta: string;
ctaHover: string;
ctaForeground: string;
filled: string;
filledHover: string;
filledForeground: string;
danger: string;
dangerHover: string;
dangerForeground: string;
}>;
spacingOverrides?: Partial<{
xs: string;
sm: string;
md: string;
lg: string;
xl: string;
}>;
radiusOverrides?: Partial<{
sm: string;
md: string;
lg: string;
full: string;
}>;
fontSizeOverrides?: Partial<{
xs: string;
sm: string;
md: string;
lg: string;
xl: string;
}>;
};All properties are optional. An empty object {} applies the default dark theme with no overrides.
Edge cases
- Multiple theme updates: Each theme message starts again from the dark default and replaces every CSS variable. There is no incremental merge. If you send
{ colorOverrides: { surface: '#1a1625' } }followed by{ primaryColor: '#e91e63' }, the second message renders the default dark surface with only the primary color changed. Always send the complete theme you want applied. - Invalid CSS color values: Nothing validates them. The embed sets the variable to whatever string you send, and any element that uses that variable loses the style (for example, a button background becomes transparent). No error is thrown. Validate colors on your side.
- Order of application: The embed starts from the dark default. If
colorOverrideshas any keys, it applies them and ignoresprimaryColor. OtherwiseprimaryColor, if set, replaces the four action tokens.spacingOverrides,radiusOverrides, andfontSizeOverridesare then applied on top.
Next steps
- Theme Playground — design your theme visually and export the code
- Deposits and Withdrawals — end-to-end integration guide
- postMessage Protocol — low-level event reference, including
PROPHETX_THEME - Error Codes — every error code and how to handle it
Updated 11 days ago
