Configure frame appearance

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

A connected customer.
A container element in your UI where you render frames.

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-sdk-web";

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

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://platform.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.

To force the appearance of every frame, not only connect, set theme on createClient() instead.

Match your brand

Pass brandColor to color the auth frame with your brand. Add customTheme to change border radius and palette. With the SDK, set both on the client-level theme:

Brand color example

const client = createClient({
  sessionToken: "...",
  theme: { brandColor: "FF6B00", customTheme: { borderRadius: "l" } },
});

See Theming for accepted color formats, every customTheme field, and the frames that apply them.

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.

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Prerequisites

Choose the right UI surface

Control light and dark appearance

Match your brand

Practical customization tips

Next steps

Frames overview

Connect frame reference

​Prerequisites

​Choose the right UI surface

​Control light and dark appearance

​Match your brand

​Practical customization tips

​Next steps

Frames overview

Connect frame reference

Prerequisites

Choose the right UI surface

Control light and dark appearance

Match your brand

Practical customization tips

Next steps