Appearance

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

​

Embedded Checkout

Customize the embedded checkout UI with the appearance prop:

<CrossmintEmbeddedCheckout
    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 Customization

The embedded checkout component has a transparent background by default. The backgroundPrimary color only affects internal components (inputs, cards) within the iframe, not the iframe body itself. To customize the overall background, wrap the component in a div with your desired background styling:

<div className="bg-gray-900">
    <CrossmintEmbeddedCheckout {...props} />
</div>

The backgroundPrimary color in your appearance configuration should complement your wrapper background for the best visual result.

​

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" },
    { cssSrc: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" }
  ]
}}

​

Global Variables

Control the overall look and feel with global variables:

appearance={{
  variables: {
    // Typography
    fontFamily: "Inter, system-ui, sans-serif",
    fontSizeUnit: "16px",

    // Spacing
    spacingUnit: "1rem",
    borderRadius: "8px",

    // Colors
    colors: {
      borderPrimary: "#E0E0E0",
      backgroundPrimary: "#FFFFFF",
      textPrimary: "#000000",
      textSecondary: "#666666",
      danger: "#FF0000",
      warning: "#FFA500",
      accent: "#0074D9"
    }
  }
}}

​

Component Rules

Style individual components through appearance.rules. Each rule accepts borderRadius, font, colors, plus state overrides like hover, focus, selected, and disabled.

Input visibility

Hide specific inputs:

appearance={{
  rules: {
    DestinationInput: {
      display: "hidden"  // Hides the wallet address input
    },
    ReceiptEmailInput: {
      display: "hidden"  // Hides the email input
    }
  }
}}

When hiding inputs, provide the corresponding values via props: recipient.walletAddress for a hidden DestinationInput, and payment.receiptEmail for a hidden ReceiptEmailInput.

Input fields, labels, and tabs

Input, Label, and Tab rules accept borderRadius, font (family, size, weight), and colors (text, background, border, boxShadow, placeholder), with hover, focus, and selected state blocks.

Primary buttons

Style the primary button, including hover and disabled states:

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"
      }
    }
  }
}}

​

Hosted Checkout

The hosted checkout exposes a smaller appearance surface: button theming, checkout display mode, and overlay behavior.

<CrossmintHostedCheckout
    appearance={{
        theme: {
            button: "light", // Options: "light", "dark", "crossmint"
            checkout: "dark", // Options: "light", "dark"
        },
        variables: {
            colors: {
                accent: "#FF0000", // Custom accent color
            },
        },
        display: "popup", // Options: "popup", "new-tab", "same-tab"
        overlay: {
            enabled: true, // Dark overlay behind the modal
        },
    }}
    // ... other props
/>

​

Headless Checkout

Headless checkout has no built-in UI — you design your own purchase preview, payment-method selection, wallet connection, and status screens. Follow the order lifecycle in How Checkout Works and reuse the status catalog in Error & Status Codes to drive your UI states.

​

Next Steps

Localization

Translate the checkout and set the payment currency

Hooks & Events

React to order updates in your own UI