Component Properties

Understand the properties available on the Checkout

If you are using our previous version of embedded checkout, please refer to the old component properties guide

Common Properties

These properties are shared between both the Embedded and Hosted checkout components.

lineItems · object | array · required

Specifies the NFTs to purchase. Can be a single item or array of items.

lineItems properties

collectionLocator · string

Collection identifier in one of these formats:

• crossmint:<_YOUR_COLLECTION_ID_>[:_TEMPLATE_ID_] - For collections created in Crossmint Console
  • Template ID is optional and requires template minting to be enabled
  • If template minting is disabled and a template ID is provided, the mint will fail with an error
• <blockchain>:<contract-address> - For collections using direct contract addresses (e.g., polygon-amoy:0xF3d2d7b5666f579DcE385b2d53c54AB1b09Ef563)

When using template minting, append the templateId to the collection locator: crossmint:collectionId:templateId. Template minting must be enabled in the Crossmint Console or the mint will fail with an error. See the Mint to Specific Template guide for details on enabling template minting and error handling.

tokenLocator · string

For secondary sales (buying existing NFTs). Token identifier in one of these formats:

• EVM chains: <blockchain>:<contractAddress>:<tokenId>
• Solana: <blockchain>:<tokenAddress>

Using tokenLocator doesn’t require registering the collection in Crossmint Console.

Use either collectionLocator (for primary sales) or tokenLocator (for secondary sales), not both.

callData · object

Arguments passed to your contract’s mint function:

Solidity

// Example mint function
function mint(
  address to,  // Auto-filled by Crossmint
  uint256 quantity,
  uint256 totalPrice
) public payable {
  // ...
}

Parameter names must match your contract’s function arguments exactly.

Do not pass the recipient argument (e.g. to) in callData. Crossmint handles this automatically.

payment · object · required

Configuration for payment methods.

payment properties

crypto · object · required

Crypto payment settings:

{
  enabled: true,  // Enable/disable crypto payments
  defaultChain: "ethereum" | "polygon" | "solana", // Optional: preferred blockchain
  defaultCurrency: "eth" | "matic" | "sol" | 'usdc' // Optional: preferred currency
}

fiat · object · required

Card & wallet payment settings:

{
  enabled: true,  // Enable/disable fiat payments
  defaultCurrency: "usd" | "eur" | "gbp",  // Optional: preferred currency
}

Embedded Checkout supports additional payment method customization. See our Embedded Checkout payment methods guide for details.

receiptEmail · string

Optional email address where purchase receipt will be sent

defaultMethod · string

Sets the default payment tab: fiat or crypto

recipient · object

Delivery details for the NFTs. You must specify either email OR wallet address, not both:

recipient properties

email · string

NFTs delivered to user’s Crossmint wallet linked to this email

walletAddress · string

NFTs delivered directly to this blockchain address

When not provided, user will be prompted during checkout.

locale · string

Sets the checkout interface language.

en-US de-DE es-ES fr-FR it-IT ja-JP ko-KR pt-PT ru-RU th-TH tr-TR uk-UA vi-VN zh-CN zh-TW Klingon

Specific Properties & Hooks

Hosted Checkout

The hosted checkout button is only available for React applications. For full customization options, please use our Headless Checkout.

The following properties are available for the CrossmintHostedCheckout component:

appearance · object

Customization options for the hosted checkout. See our UI Customization guide for complete details.

Notable appearance options:

• Display mode: display: "popup" | "new-tab" (default: “popup”)
• Background overlay: overlay.enabled: false to disable the gray background
• Button theme: theme.button: "light" | "dark" | "crossmint" (default: “light”)
• Checkout theme: theme.checkout: "light" | "dark" (default: “light”)

The hosted checkout button is only available for React applications. For full customization options, please use our Headless Checkout.

The following properties are available for the CrossmintHostedCheckout component:

appearance · object

Customization options for the hosted checkout. See our UI Customization guide for complete details.

Notable appearance options:

• Display mode: display: "popup" | "new-tab" (default: “popup”)
• Background overlay: overlay.enabled: false to disable the gray background
• Button theme: theme.button: "light" | "dark" | "crossmint" (default: “light”)
• Checkout theme: theme.checkout: "light" | "dark" (default: “light”)

The embedded checkout is only available for React applications. For full customization options, please use our Headless Checkout.

The following properties are available for the CrossmintEmbeddedCheckout component:

payment · object · required

Extends the common payment configuration with additional options.

payment properties

fiat · object · required

Extended fiat payment settings:

{
  enabled: true,  // Enable/disable fiat payments
  defaultCurrency: "usd" | "eur" | "gbp",  // Optional: preferred currency
  allowedMethods: {
    card: boolean,       // Credit/debit cards
    applePay: boolean,   // Apple Pay
    googlePay: boolean   // Google Pay
  }
}

appearance

Customization options for the checkout UI. See our UI Customization guide for complete details.

Notable appearance options:

• Hide destination input: rules.DestinationInput.display: "hidden"
• Hide receipt email input: rules.ReceiptEmailInput.display: "hidden"

If inputs are hidden, you must provide the corresponding values via recipient/payment props.

The following React hooks are available for use with the Embedded Checkout:

useCrossmintCheckout · function

The useCrossmintCheckout hook is used to access the current order and checkout state.

All Crossmint hooks must be used within components wrapped by both CrossmintProvider and CrossmintCheckoutProvider:

<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintCheckoutProvider>
        <YourComponent /> {/* Hooks can be used here */}
    </CrossmintCheckoutProvider>
</CrossmintProvider>

The following properties are available from the useCrossmintCheckout hook:

order · object

The current order object containing all order details.

Order properties

orderId · string

Unique identifier for the order

phase · string

Current phase of the order: quote | payment | delivery | completed

lineItems · array

Array of items being purchased.

lineItem properties

chain · string

Blockchain network for the NFT

quantity · number

Number of NFTs being purchased

metadata · object

{
  name: string;
  description: string;
  imageUrl: string;
  collection: {
      name: string;
      description: string;
      imageUrl: string;
  };
}

quote · object

{
  status: "valid" | "item-unavailable" | "expired" | "requires-recipient";
  charges: {
      unit: { currency: string; amount: string; };
      gas: { currency: string; amount: string; };
  };
  totalPrice: { currency: string; amount: string; };
}

delivery · object

NFT delivery status and details:

// When completed:
{
  status: "completed";
  txId: string;
  tokens: [{
      locator: string;
      contractAddress: string;
      tokenId: string;
      mintHash: string;
  }];
  recipient: {
      walletAddress: string;
      locator: string;
      email: string;
  };
}

// When in progress:
{
  status: "awaiting-payment" | "in-progress" | "failed";
  recipient: {
      walletAddress: string;
      locator: string;
      email: string;
  };
}

quote · object

Order quote status and pricing:

{
  status: "valid" | "expired" | "requires-recipient" | "all-line-items-unavailable";
  quotedAt: string;
  expiresAt: string;
  totalPrice: {
      currency: string;
      amount: string;
  };
}