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

​
Setup Requirements

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

import { CrossmintProvider, CrossmintCheckoutProvider, useCrossmintCheckout } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_API_KEY">
            <CrossmintCheckoutProvider>
                <YourCheckoutComponent />
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}

​
useCrossmintCheckout

The useCrossmintCheckout hook provides access to the checkout state and allows you to build custom UI experiences.

​
Return Values

PropertyTypeDescription
orderOrder | undefinedThe current order object containing all order details
orderClientSecretstring | undefinedThe client secret for the current order

​
Order Phases

The order can be in one of the following phases:

  • quote - Initial phase where price quotes are being generated
  • payment - Payment is being processed
  • delivery - NFTs are being delivered to the recipient
  • completed - Order has been successfully completed

For more information on the order lifecycle, see our Order Lifecycle guide.

Here’s how you can use the order data to track the purchase progress:

function PurchaseStatus() {
    const { order } = useCrossmintCheckout();

    // Create a custom notification based on the current phase
    const getMessage = () => {
        if (!order) return "Initializing...";

        switch (order.phase) {
            case "quote":
                return `Preparing order: ${order.lineItems.length} items`;
            case "payment":
                return `Processing ${order.payment.method} payment`;
            case "delivery":
                return "Delivering NFTs to wallet...";
            case "completed":
                return "Purchase successful!";
        }
    };

    return <div className="status-message">{getMessage()}</div>;
}

For more information on the order object, see our Order Properties section.

​
Complete Example

Here’s a full example showing how to implement a custom checkout experience:

import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintEmbeddedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

function CheckoutPage() {
    return (
        <CrossmintProvider apiKey="YOUR_API_KEY">
            <CrossmintCheckoutProvider>
                <div className="checkout-container">
                    <CrossmintEmbeddedCheckout
                        lineItems={{
                            collectionLocator: "crossmint:your-collection-id",
                            callData: {
                                totalPrice: "0.001",
                                quantity: 1,
                            },
                        }}
                        payment={{
                            crypto: { enabled: true },
                            fiat: { enabled: true },
                        }}
                    />
                    <CheckoutStatus />
                </div>
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}

function CheckoutStatus() {
    const { order } = useCrossmintCheckout();

    if (!order) {
        return <div>Loading...</div>;
    }

    switch (order.phase) {
        case "completed":
            return <div>Purchase complete!</div>;
        case "delivery":
            return <div>Delivering your NFTs...</div>;
        case "payment":
            return <div>Processing payment...</div>;
        case "quote":
            return <div>Preparing your order...</div>;
    }
}

​
Best Practices

  1. Provider Setup: Always ensure components using hooks are wrapped with both required providers
  2. Error Handling: Handle undefined states when accessing order properties
  3. Loading States: Provide appropriate loading UI while the order state is initializing
  4. Type Safety: Take advantage of TypeScript support for better development experience

​
Migration from Previous Version

If you’re migrating from the previous version, note these key differences:

  • The event system has been replaced with the useCrossmintCheckout hook
  • Order status is now accessed through the hook instead of event listeners
  • Custom UI is built using React components instead of event handlers
  • Components must be wrapped with required providers

The new hook-based approach provides a more React-friendly experience and better TypeScript support compared to the previous event system.

Payment MethodsApple Pay Integration Guide