UI Customization

​

Prerequisites

• An integration that shows the KYC screens: the embedded checkout for onramp or offramp, or the standalone verification component.

​

Before You Start

• The KYC screens read the same appearance object that you pass to the embedded checkout. If checkout already uses your brand, the KYC screens use it too, and there is nothing else to configure.
• Every setting is optional. A setting that you do not set uses the Crossmint default.
• If one value is not valid (for example, a color with a typo), the screens ignore all of your settings and show the default look. No error message shows, so test after each change.
• The ID document and selfie step (full verification only) has one light look and one dark look. Your colors and fonts do not apply to it. See Light and Dark Mode.

​

Apply Your Theme

import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

// Order created on your server with POST /api/2022-06-09/orders
const order = { orderId: "YOUR_ORDER_ID", clientSecret: "YOUR_ORDER_CLIENT_SECRET" };

<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",
            borderRadius: "12px",
            colors: {
                backgroundPrimary: "#FFFFFF",
                textPrimary: "#00150D",
                textSecondary: "#67797F",
                borderPrimary: "#D1D5DB",
                accent: "#0074D9",
                danger: "#DC2626",
            },
        },
        rules: {
            PrimaryButton: {
                colors: { background: "#0074D9", text: "#FFFFFF" },
                hover: { colors: { background: "#0063B8" } },
                disabled: { colors: { background: "#E7E9ED", text: "#67797F" } },
            },
        },
    }}
/>;

​

Appearance Settings and Where They Apply

​

Default Colors

​

Light and Dark Mode

• An opaque dark color (for example #1E2023) selects the dark defaults.
• A light color, a transparent or semi-transparent color, or no value selects the light defaults.

​

Fonts, Sizes, and Corners

​

Good Practices

• Check contrast against the background. Text colors need a contrast of at least 4.5:1 against backgroundPrimary. Accent and borders need at least 3:1.
• Use a darker accent for a pale brand color. Use the pale color on the button, with dark text. For accent, use a darker shade so links and field borders stay visible.
• Set all button states. Set background, text, hover, and disabled. The button stays disabled until the user fills the fields, so users see that state often.
• Use a font made for body text. The font shows at 16px in fields and smaller in hints. Thin or decorative fonts are hard to read at that size. Load the regular, medium, and semibold weights.
• Keep the error color red. Users must see a field with an error immediately. Do not use your brand color for danger.
• Use one plain background color. backgroundPrimary takes one color. Gradients and images are not possible. Put brand images on your page, outside the KYC screens.

​

Place the Screens on Your Page

• Safe area. Leave 24px of space on all four sides of the iframe. The screens do not include it; your page must add it.
• Height. Let the iframe grow with the screen inside it. Do not set a fixed height, or the Continue button gets cut off.
• Overlays. Nothing should cover the Continue button, such as a cookie banner or a bottom bar.
• Background. Give your page the same background color as backgroundPrimary, or the edge of the iframe shows.
• Width. On phones, keep the 24px safe area on each side inside the screen width and let the iframe fill the remaining space. On desktop, use the same width as your checkout.
• Camera. The ID document and selfie step uses the camera. The Crossmint SDK allows it on the iframe. If you render the iframe without the SDK, allow the camera on it with allow="camera".
• Narrow phones. Test on a screen 360px wide. Many Android phones have this width.

​

What You Cannot Change

​

Test Your Theme

• Your checkout settings show on the KYC screens.
• Light mode and dark mode, if your app has both.
• A full verification with a higher amount: the ID document and selfie step shows in the correct mode.
• An empty field and an incorrect value: the error color shows.
• The hover and disabled states of the button.
• A phone 360px wide and a desktop: the button is fully visible and the page does not scroll sideways.

​

Next Steps