React Hooks

Learn how to use React hooks to control and customize your Embedded Checkout experience

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

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.

Related Resources

• UI Customization
• Payment Methods
• Order Lifecycle
• Testing Tips