Skip to main content
This integration is currently in preview and subject to change.
Use this guide to keep co-branded frames consistent with the rest of your UI. Frames render MoonPay-hosted UI inside your app, so presentation choices affect how the flow feels to customers.

​
Prerequisites

​
Choose the right UI surface

  • Web: Render co-branded frames in a modal or sheet and keep the rest of your UI visible behind it.
  • Mobile: Present co-branded frames in a full-screen route or full sheet. This reduces layout issues when the frame navigates between steps.

​
Control light and dark appearance

The connect frame supports a theme parameter. Use it to force dark or light instead of relying on the user’s system appearance. If you use the SDK, pass theme when you initialize the connect flow:
Set appearance example
import { createClient } from "@moonpay/platform";

const clientResult = createClient({ sessionToken: "..." });
const client = clientResult.value;

const connectResult = await client.connect({
  container: connectContainer,

  theme: {
    appearance: "dark", // Force dark mode
  },

  onEvent: (event) => {
    // Handle events
  },
});
If you build the connect frame URL manually, include theme in the query string:
Example URL
https://blocks.moonpay.com/platform/v1/connect?sessionToken=c3N0XzAwMQ==&publicKey=...&channelId=ch_1&theme=dark
If you omit theme, the frame uses the user’s system preference.

​
Practical customization tips

  • Avoid resizing containers mid-flow: Use a stable container size while the frame is mounted to prevent content jumps.
  • Show clear loading states: If you wait for a frame’s ready event, keep your UI responsive and show a spinner/skeleton.
  • Plan for errors: If a frame dispatches an error event, show a developer-friendly fallback (retry, exit, or contact support).

​
Next steps

Frames overview

Learn the shared messaging protocol for integrating without the SDK.

Connect frame reference

See all initialization parameters including theme.