Hooks & Events

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

A custom checkout experience that renders your own status UI next to the embedded component:

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

function CheckoutPage() {
    return (
        <CrossmintProvider apiKey="<your-client-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 items...</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

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Setup Requirements

useCrossmintCheckout

Return Values

Order Phases

Complete Example

Best Practices

Next Steps

Track Orders

Handle Errors

​Setup Requirements

​useCrossmintCheckout

​Return Values

​Order Phases

​Complete Example

​Best Practices

​Next Steps

Track Orders

Handle Errors

Setup Requirements

useCrossmintCheckout

Return Values

Order Phases

Complete Example

Best Practices

Next Steps