UI Customization

Customize the onramp checkout UI to match your brand identity and design system

The onramp embedded checkout component supports extensive customization through the appearance prop, allowing you to match the look and feel of your application.

Quick Start

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={order.clientSecret}
    appearance={{
        fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }],
        variables: {
            fontFamily: "Inter, system-ui, sans-serif",
            colors: {
                backgroundPrimary: "#ffffff",
                textPrimary: "#000000",
                accent: "#0074D9",
            },
        },
    }}
/>

Identity Verification Screens

When an order requires KYC, the identity verification screens render inside the checkout and read the same appearance object, so your theme applies to them without extra configuration. There is no separate theme key: an opaque dark backgroundPrimary switches the screens to their dark defaults. See the identity verification UI customization guide for the settings that apply, the default colors, and how to place the screens on your page.

Customization Options

Background

The embedded checkout component has a transparent background by default. The backgroundPrimary color only affects internal components (inputs, cards, etc.) within the iframe, not the iframe body itself.

To customize the overall background, wrap the component:

<div style={{ backgroundColor: "#1a1a1a" }}>
    <CrossmintEmbeddedCheckout {...props} />
</div>

Custom Fonts

Load custom fonts using the fonts array:

appearance={{
    fonts: [
        { cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }
    ]
}}

Global Variables

Control the overall look and feel:

appearance={{
    variables: {
        fontFamily: "Inter, system-ui, sans-serif",
        fontSizeUnit: "16px",
        spacingUnit: "1rem",
        borderRadius: "8px",
        colors: {
            borderPrimary: "#E0E0E0",
            backgroundPrimary: "#FFFFFF",
            textPrimary: "#000000",
            textSecondary: "#666666",
            danger: "#FF0000",
            warning: "#FFA500",
            accent: "#0074D9"
        }
    }
}}

Component Rules

Input Visibility

Control the visibility of specific inputs:

appearance={{
    rules: {
        DestinationInput: {
            display: "hidden"
        },
        ReceiptEmailInput: {
            display: "hidden"
        }
    }
}}

When hiding inputs, make sure to provide the corresponding values via props:

• For hidden DestinationInput, provide recipient.walletAddress
• For hidden ReceiptEmailInput, provide payment.receiptEmail

Labels

Customize label styling:

appearance={{
    rules: {
        Label: {
            font: {
                family: "Inter",
                size: "14px",
                weight: "500",
            },
            colors: {
                text: "#333333",
            },
        },
    },
}}

Input Fields

Style input fields:

appearance={{
    rules: {
        Input: {
            borderRadius: "8px",
            font: {
                family: "Inter",
                size: "16px",
                weight: "400",
            },
            colors: {
                text: "#000000",
                background: "#FFFFFF",
                border: "#E0E0E0",
                boxShadow: "none",
                placeholder: "#999999",
            },
            hover: {
                colors: {
                    border: "#0074D9",
                },
            },
            focus: {
                colors: {
                    border: "#0074D9",
                    boxShadow: "0 0 0 2px rgba(0,116,217,0.2)",
                },
            },
        },
    },
}}

Tabs

Customize tab appearance:

appearance={{
    rules: {
        Tab: {
            borderRadius: "4px",
            font: {
                family: "Inter",
                size: "14px",
                weight: "500",
            },
            colors: {
                text: "#666666",
                background: "transparent",
            },
            selected: {
                colors: {
                    text: "#000000",
                    background: "#F5F5F5",
                },
            },
            hover: {
                colors: {
                    background: "#F0F0F0",
                },
            },
        },
    },
}}

Primary Buttons

Style primary buttons:

appearance={{
    rules: {
        PrimaryButton: {
            borderRadius: "8px",
            font: {
                family: "Inter",
                size: "16px",
                weight: "600"
            },
            colors: {
                text: "#FFFFFF",
                background: "#0074D9"
            },
            hover: {
                colors: {
                    background: "#0063B8"
                }
            },
            disabled: {
                colors: {
                    text: "#FFFFFF",
                    background: "#CCCCCC"
                }
            }
        }
    }
}}

Common Examples

Modern Dark Theme

appearance={{
    variables: {
        fontFamily: "Inter, system-ui, sans-serif",
        colors: {
            backgroundPrimary: "#1A1A1A",
            textPrimary: "#FFFFFF",
            textSecondary: "#A0A0A0",
            borderPrimary: "#333333",
            accent: "#7928CA"
        }
    },
    rules: {
        Input: {
            colors: {
                background: "#2D2D2D",
                border: "#404040",
                text: "#FFFFFF",
                placeholder: "#666666"
            }
        },
        PrimaryButton: {
            colors: {
                background: "#7928CA",
                text: "#FFFFFF"
            },
            hover: {
                colors: {
                    background: "#6B24B2"
                }
            }
        }
    }
}}

Minimal Light Theme

appearance={{
    variables: {
        fontFamily: "system-ui, sans-serif",
        borderRadius: "4px",
        colors: {
            backgroundPrimary: "#FFFFFF",
            textPrimary: "#000000",
            borderPrimary: "#E0E0E0",
            accent: "#000000"
        }
    },
    rules: {
        Input: {
            borderRadius: "4px",
            colors: {
                background: "#F5F5F5",
                border: "transparent"
            },
            focus: {
                colors: {
                    border: "#000000",
                    boxShadow: "none"
                }
            }
        },
        PrimaryButton: {
            borderRadius: "4px",
            colors: {
                background: "#000000",
                text: "#FFFFFF"
            }
        }
    }
}}

Related Resources

• React Quickstart
• React Native Quickstart
• User Onboarding
• Identity Verification UI Customization