Theming Guide

What you'll learn

1. Use the Theme Playground — visually design a theme and copy the integration snippet.
2. Apply a base theme — switch between light and dark mode, set a primary brand color.
3. Override individual tokens — fine-tune colors, spacing, border radius, and font sizes.
4. 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:

1. Open the Theme Playground.
2. Use the sidebar controls to pick an accent color, adjust border radius and spacing scales, switch between light and dark mode, and edit individual color tokens.
3. The preview panel updates instantly so you can see how your theme looks across every embed state.
4. When you're happy, copy the integration snippet at the bottom of the sidebar — it contains only the values that differ from the default theme, ready to paste into your code.

📘

Tip

Use the Theme Playground to test your theme before writing any code. It generates a minimal EmbedTheme object 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.

Basic theming

The simplest theme sets a mode and a primaryColor:

const THEME = {
  mode: 'dark',
  primaryColor: '#e91e63',
};

Setting mode swaps the entire color palette between light and dark presets. Setting primaryColor overrides the four action-color variables so buttons and interactive elements match your brand. These two properties are enough for most integrations. To customize the page background, use colorOverrides.background — see Granular overrides below.

SDK integration

Updating the theme at runtime

You may want to change the theme after the embed is already mounted — for example, when a user toggles dark mode in your app.

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 default value in each mode, and what it controls.

Colors

Spacing

Border radius

Font size

Font family

📘

Note

Font family is not currently overridable via ThemePayload. "GT America" is the ProphetX brand font; the system fallbacks render if it's unavailable.

Granular overrides

For full control beyond mode and primaryColor, use the override properties. Each one accepts a partial object — you only need to include the tokens you want to change. Unspecified tokens keep their default values for the selected mode.

colorOverrides

Override any individual color token. Useful when primaryColor isn't enough — for example, matching your brand's error color or surface tones.

const THEME: EmbedTheme = {
  mode: "light",
  primaryColor: "#7c3aed",
  colorOverrides: {
    surface: "#faf5ff",
    surfaceElevated: "#f3e8ff",
    border: "#e9d5ff",
    borderSubtle: "#f3e8ff",
    cta: "#7c3aed",
    ctaHover: "#6d28d9",
    ctaForeground: "#ffffff",
    success: "#059669",
    successBackground: "#ecfdf5",
  },
};

Available keys:

spacingOverrides

Adjust the spacing scale to match your design system. Values are CSS length strings.

const THEME: EmbedTheme = {
  mode: "light",
  spacingOverrides: {
    xs: "0.125rem",
    sm: "0.375rem",
    md: "0.75rem",
    lg: "1.25rem",
    xl: "1.75rem",
  },
};

radiusOverrides

Control 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 = {
  mode: "light",
  radiusOverrides: {
    sm: "0.5rem",
    md: "0.75rem",
    lg: "1rem",
  },
};

fontSizeOverrides

Scale typography up or down. Useful if your app uses a different base font size.

const THEME: EmbedTheme = {
  mode: "light",
  fontSizeOverrides: {
    xs: "0.625rem",
    sm: "0.75rem",
    md: "0.875rem",
    lg: "1rem",
    xl: "1.125rem",
  },
};

Full example

Here's a complete theme that combines mode, primary color, and granular overrides — the kind of object the Theme Playground generates for you:

ThemePayload reference

The complete type accepted by the SDK's theme prop and updateTheme():

type ThemePayload = {
  mode?: 'light' | 'dark';
  primaryColor?: string;
  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 light theme with no overrides.

Edge cases

• Multiple theme updates: Each theme message fully replaces all CSS variables. There is no incremental merge — if you send { mode: 'dark' } followed by { primaryColor: '#e91e63' }, the second message uses the light theme (default) with only the primary color changed. Always send the complete theme you want applied.
• Invalid CSS color values: The embed silently ignores invalid color strings. No error is thrown, but the variable won't update — the previous value remains.
• Order of application: mode selects the base palette first, then primaryColor overrides the four action tokens, then colorOverrides / spacingOverrides / radiusOverrides / fontSizeOverrides are 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