React Hooks

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

Property	Type	Description
`order`	`Order \| undefined`	The current order object containing all order details
`orderClientSecret`	`string \| undefined`	The 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

Provider Setup: Always ensure components using hooks are wrapped with both required providers
Error Handling: Handle undefined states when accessing order properties
Loading States: Provide appropriate loading UI while the order state is initializing
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.

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

Setup Requirements

useCrossmintCheckout

Return Values

Order Phases

Complete Example

Best Practices

Migration from Previous Version

​Setup Requirements

​useCrossmintCheckout

​Return Values

​Order Phases

​Complete Example

​Best Practices

​Migration from Previous Version

​Related Resources

Setup Requirements

useCrossmintCheckout

Return Values

Order Phases

Complete Example

Best Practices

Migration from Previous Version

Related Resources