React Hooks

Learn how to use React hooks to control and customize the Hosted Checkout UI

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,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

function CheckoutPage() {
    return (
        <CrossmintProvider apiKey="YOUR_API_KEY">
            <CrossmintCheckoutProvider>
                <CrossmintHostedCheckout
                    lineItems={{
                        collectionLocator: "crossmint:your-collection-id",
                        callData: {
                            totalPrice: "0.001",
                            quantity: 1,
                        },
                    }}
                    payment={{
                        crypto: { enabled: true },
                        fiat: { enabled: true },
                    }}
                />
                <CheckoutStatus />
            </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

Related Resources

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