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

  1. Use the Theme Playground — visually design a theme and copy the integration snippet.
  2. Set your brand color — or send a complete light palette.
  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 to pick an accent color, choose a border radius preset, scale the font sizes, and edit individual color, spacing, radius, and font-size 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 dark theme, ready to paste into your code. A light theme differs from dark in every color, so its snippet is a complete colorOverrides palette.
📘

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. 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',
};
PropertyTypeDescription
primaryColorstringAny 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 when primaryColor or backgroundColor changes.

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

VariableLight paletteDark (default)Used for
--color-primary#3ECF8E#3ECF8EPrimary actions, links
--color-primary-hover#2EBF7E#2EBF7EPrimary hover state
--color-primary-foreground#FFFFFF#0D1117Text on primary backgrounds
--color-primary-background#ecfdf5#022c22Selected-state fill (e.g. a chosen payment method)
--color-secondary#4C526B#9196A5Secondary actions
--color-secondary-hover#383F5A#ADADB9Secondary hover state
--color-background#FFFFFF#0D1117Input fields, inset panels
--color-surface#F6F8FA#161B22Embed background, cards
--color-surface-elevated#FFFFFF#21262DElevated card backgrounds
--color-text#24292F#FFFFFFPrimary text
--color-text-muted#57606A#8B949ESecondary text
--color-text-subtle#6E7681#6E7681Hint and placeholder text
--color-border#D0D7DE#30363DBorders, dividers
--color-border-subtle#D8DEE4#21262DSubtle dividers
--color-error#F2586B#F2586BError text, icons
--color-error-background#fef2f2#450a0aError banner backgrounds
--color-success#52CEA6#52CEA6Success text, icons
--color-success-background#f0fdf4#052e16Success banner backgrounds
--color-warning#ca8a04#eab308Warning text, icons
--color-warning-background#fefce8#422006Warning banner backgrounds
--color-cta#52CEA6#52CEA6Call-to-action button background
--color-cta-hover#A1E6B6#A1E6B6CTA hover state
--color-cta-foreground#0D1117#0D1117Text on CTA buttons
--color-filled#1A2135#1A2135Filled variant button background
--color-filled-hover#2A324A#2A324AFilled button hover state
--color-filled-foreground#FFFFFF#FFFFFFText on filled buttons
--color-danger#F2586B#F2586BDestructive action button background
--color-danger-hover#D94A5C#D94A5CDanger hover state
--color-danger-foreground#FFFFFF#FFFFFFText on danger buttons

Spacing

VariableDefaultUsed for
--spacing-xs4pxTight gaps, inline padding
--spacing-sm8pxSmall gaps between related elements
--spacing-md16pxStandard padding, section gaps
--spacing-lg24pxCard padding, group spacing
--spacing-xl32pxSection margins, large gaps

Border radius

VariableDefaultUsed for
--radius-sm4pxInputs, small elements
--radius-md8pxButtons, badges
--radius-lg12pxCards, modals
--radius-full9999pxPills, avatars

Font size

VariableDefaultUsed for
--font-size-xs0.75remCaptions, fine print
--font-size-sm0.875remSecondary text, labels
--font-size-md1remBody text
--font-size-lg1.125remSubheadings
--font-size-xl1.25remHeadings
--font-size-2xl1.5remLarge figures (e.g. the balance)

Font family

VariableDefault
--font-sans"GT America", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif
--font-mono"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace
📘

Note

Font 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-background and --font-size-2xl are applied when you send colorOverrides.primaryBackground or fontSizeOverrides["2xl"], but they aren't in the TypeScript EmbedTheme type 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

Override 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:

KeyMaps 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

Adjust 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",
  },
};
KeyMaps to CSS variableDefault
xs--spacing-xs4px
sm--spacing-sm8px
md--spacing-md16px
lg--spacing-lg24px
xl--spacing-xl32px

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 = {
  radiusOverrides: {
    sm: "0.5rem",
    md: "0.75rem",
    lg: "1rem",
  },
};
KeyMaps to CSS variableDefault
sm--radius-sm4px
md--radius-md8px
lg--radius-lg12px
full--radius-full9999px

fontSizeOverrides

Scale 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",
  },
};
KeyMaps to CSS variableDefault
xs--font-size-xs0.75rem
sm--font-size-sm0.875rem
md--font-size-md1rem
lg--font-size-lg1.125rem
xl--font-size-xl1.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

The 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 colorOverrides has any keys, it applies them and ignores primaryColor. Otherwise primaryColor, if set, replaces the four action tokens. spacingOverrides, radiusOverrides, and fontSizeOverrides are then applied on top.

Next steps



Did this page help you?