> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appearance

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

## Embedded Checkout

Customize the embedded checkout UI with the `appearance` prop:

```tsx theme={null}
<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

<Snippet file="identity-kyc-appearance.mdx" />

## 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:

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

> [!NOTE]
>
> 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:

```tsx theme={null}
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:

```tsx theme={null}
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`.

> [accordion] Input visibility
>
> Hide specific inputs:
>
> ```tsx theme={null}
> appearance={{
>   rules: {
>     DestinationInput: {
>       display: "hidden"  // Hides the wallet address input
>     },
>     ReceiptEmailInput: {
>       display: "hidden"  // Hides the email input
>     }
>   }
> }}
> ```
>
> > [!NOTE]
> >
> > When hiding inputs, provide the corresponding values via props: `recipient.walletAddress` for a hidden
> > `DestinationInput`, and `payment.receiptEmail` for a hidden `ReceiptEmailInput`.

> [accordion] 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.

> [accordion] Primary buttons
>
> Style the primary button, including `hover` and `disabled` states:
>
> ```tsx theme={null}
> 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

> [accordion] Modern dark theme
>
> ```tsx theme={null}
> 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"
>         }
>       }
>     }
>   }
> }}
> ```

> [accordion] Minimal light theme
>
> ```tsx theme={null}
> 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.

```tsx theme={null}
<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](https://docs.crossmint.com/payments/concepts/how-checkout-works.md) and reuse the status catalog in [Error & Status Codes](https://docs.crossmint.com/payments/reference/error-and-status-codes.md) to drive your UI states.

## Next Steps

> [card] [Localization](https://docs.crossmint.com/payments/guides/localization.md)
>
> Translate the checkout and set the payment currency

> [card] [Hooks & Events](https://docs.crossmint.com/payments/guides/hooks-and-events.md)
>
> React to order updates in your own UI