React UI SDK - Crossmint SDK

Installation

npm install @crossmint/client-sdk-react-ui

Setup

Wrap your application with CrossmintProvider to initialize the SDK:

import { CrossmintProvider } from '@crossmint/client-sdk-react-ui';

function App() {
  return (
    <CrossmintProvider apiKey="YOUR_API_KEY">
      {/* Your app components */}
    </CrossmintProvider>
  );
}

Provider Props

apiKey

string

required

Your Crossmint API key from the Developer Console

consoleLogLevel

'debug' | 'info' | 'warn' | 'error' | 'silent'

default:"debug"

Minimum log level for console output. Set to "silent" to suppress all logs.

overrideBaseUrl

string

Override the default API base URL (for testing purposes)

Authentication

CrossmintAuthProvider

Enables authentication with multiple methods including email, OAuth, and Web3 wallets.

import { CrossmintAuthProvider } from '@crossmint/client-sdk-react-ui';

function App() {
  return (
    <CrossmintProvider apiKey="YOUR_API_KEY">
      <CrossmintAuthProvider
        loginMethods={['email', 'google', 'twitter', 'farcaster', 'web3-metamask']}
        onLoginSuccess={(user) => console.log('Logged in:', user)}
      >
        {/* Your app */}
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

Props

Available login methods. Options:

'email' - Email OTP authentication
'google' - Google OAuth
'twitter' - Twitter OAuth
'farcaster' - Farcaster Sign In With Farcaster
'web3-metamask' - MetaMask wallet
'web3-coinbase' - Coinbase Wallet
'web3-walletconnect' - WalletConnect

appearance

UIConfig

Customize the auth UI appearance

appearance={{
  colors: {
    textPrimary: '#000000',
    textSecondary: '#666666',
    accent: '#00D091',
  },
}}

Callback fired when user successfully authenticates

Custom title for the authentication modal

termsOfServiceText

string

Custom terms of service text shown during authentication

prefetchOAuthUrls

boolean

default:true

Whether to prefetch OAuth URLs for faster login

useCrossmintAuth Hook

Access authentication state and methods:

import { useCrossmintAuth } from '@crossmint/client-sdk-react-ui';

function LoginButton() {
  const { login, logout, status, user, jwt } = useCrossmintAuth();

  if (status === 'authenticated') {
    return (
      <div>
        <p>Logged in as {user?.email}</p>
        <button onClick={logout}>Sign Out</button>
      </div>
    );
  }

  return (
    <button onClick={() => login()}>Sign In</button>
  );
}

Return Values

status

'initializing' | 'authenticated' | 'not-authenticated'

Current authentication status

user

SDKExternalUser | undefined

Authenticated user object with email, userId, and linkedAccounts

jwt

string | undefined

JWT token for the authenticated user

Opens the authentication modal. Optionally pre-fill email.

logout

() => Promise<void>

Signs out the current user

Programmatically trigger OAuth login for a specific provider

EmbeddedAuthForm Component

Embedded authentication form for custom layouts:

import { EmbeddedAuthForm } from '@crossmint/client-sdk-react-ui';

function CustomAuthPage() {
  return (
    <div className="auth-container">
      <h1>Sign In</h1>
      <EmbeddedAuthForm />
    </div>
  );
}

Wallet Management

CrossmintWalletProvider

Manages custodial wallet creation and transactions.

import { CrossmintWalletProvider } from '@crossmint/client-sdk-react-ui';

function App() {
  return (
    <CrossmintProvider apiKey="YOUR_API_KEY">
      <CrossmintAuthProvider>
        <CrossmintWalletProvider
          createOnLogin={{ chain: 'ethereum' }}
          callbacks={{
            onWalletCreationStart: async () => console.log('Creating wallet...'),
            onTransactionStart: async () => console.log('Transaction starting...'),
          }}
        >
          {/* Your app */}
        </CrossmintWalletProvider>
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

Props

Automatically create a wallet when user logs in

createOnLogin={{ chain: 'ethereum' | 'solana' | 'stellar' }}

showPasskeyHelpers

boolean

default:true

Show UI helpers for passkey creation and management

appearance

UIConfig

Customize wallet UI appearance

callbacks

object

Lifecycle callbacks:

onWalletCreationStart - Called before wallet creation
onTransactionStart - Called before transaction signing

useWallet Hook

Access wallet state and methods:

import { useWallet } from '@crossmint/client-sdk-react-ui';
import type { EVMWallet } from '@crossmint/client-sdk-react-ui';

function WalletInfo() {
  const { wallet, status } = useWallet<EVMWallet>();

  if (status === 'not-loaded') {
    return <div>No wallet</div>;
  }

  return (
    <div>
      <p>Address: {wallet.address}</p>
      <p>Chain: {wallet.chain}</p>
      <button onClick={async () => {
        const balance = await wallet.getBalance();
        console.log('Balance:', balance);
      }}>
        Get Balance
      </button>
    </div>
  );
}

Return Values

wallet

Wallet

Wallet instance (EVMWallet, SolanaWallet, or StellarWallet) with methods:

address - Wallet address
chain - Blockchain identifier
getBalance() - Fetch wallet balance
signMessage(message) - Sign arbitrary message
sendTransaction(tx) - Send transaction

status

'not-loaded' | 'loading' | 'loaded'

Current wallet loading status

ExportPrivateKeyButton

Pre-built button to export wallet private keys:

import { ExportPrivateKeyButton } from '@crossmint/client-sdk-react-ui';

function WalletSettings() {
  return (
    <div>
      <h3>Wallet Security</h3>
      <ExportPrivateKeyButton />
    </div>
  );
}

Checkout Components

CrossmintEmbeddedCheckout

Embedded checkout iframe for accepting payments and minting NFTs:

import { CrossmintEmbeddedCheckout } from '@crossmint/client-sdk-react-ui';

function CheckoutPage() {
  return (
    <CrossmintEmbeddedCheckout
      lineItems={{
        collectionLocator: 'crossmint:collection-id',
        callData: {
          totalPrice: '0.1',
          quantity: 1,
        },
      }}
      payment={{
        crypto: { enabled: true },
        fiat: { enabled: true },
      }}
      recipient={{
        email: '[email protected]',
        wallet: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      }}
      onEvent={(event) => {
        console.log('Checkout event:', event);
      }}
    />
  );
}

Props

lineItems

object

required

Items to purchase:

{
  collectionLocator: 'crossmint:collection-id',
  callData: { totalPrice: '0.1', quantity: 1 }
}

payment

object

Payment method configuration:

{
  crypto: { enabled: true },
  fiat: { enabled: true }
}

recipient

object

Recipient details:

{
  email: '[email protected]',
  wallet: '0x...' // Optional delivery address
}

locale

string

Checkout UI locale (e.g., ‘en-US’, ‘es-ES’)

appearance

object

Customize checkout appearance

onEvent

(event) => void

Callback for checkout events (e.g., ‘order:created’, ‘order:completed’)

CrossmintHostedCheckout

Button that opens checkout in a popup window:

import { CrossmintHostedCheckout } from '@crossmint/client-sdk-react-ui';

function BuyButton() {
  return (
    <CrossmintHostedCheckout
      lineItems={{ collectionLocator: 'collection-id' }}
      payment={{ crypto: { enabled: true } }}
    >
      Buy Now
    </CrossmintHostedCheckout>
  );
}

Accepts the same props as CrossmintEmbeddedCheckout plus all HTML button attributes.

useCrossmintCheckout Hook

Access current checkout order state:

import { useCrossmintCheckout } from '@crossmint/client-sdk-react-ui';

function OrderStatus() {
  const { order, orderClientSecret } = useCrossmintCheckout();

  if (!order) return null;

  return (
    <div>
      <p>Order ID: {order.id}</p>
      <p>Status: {order.status}</p>
      <p>Total: {order.totalPrice}</p>
    </div>
  );
}

NFT Display Components

CrossmintNFTCollectionView

Display NFTs from a collection:

import { CrossmintNFTCollectionView } from '@crossmint/client-sdk-react-ui';

function MyNFTs() {
  return (
    <CrossmintNFTCollectionView
      walletAddress="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      chain="ethereum"
    />
  );
}

CrossmintNFTDetail

Display details for a single NFT:

import { CrossmintNFTDetail } from '@crossmint/client-sdk-react-ui';

function NFTPage() {
  return (
    <CrossmintNFTDetail
      tokenId="1"
      contractAddress="0x..."
      chain="ethereum"
    />
  );
}

Payment Management

CrossmintPaymentMethodManagement

Component for managing saved payment methods:

import { CrossmintPaymentMethodManagement } from '@crossmint/client-sdk-react-ui';

function PaymentSettings() {
  return (
    <div>
      <h2>Payment Methods</h2>
      <CrossmintPaymentMethodManagement
        onUpdate={(methods) => console.log('Updated:', methods)}
      />
    </div>
  );
}

Hooks Reference

See source at /home/daytona/workspace/source/packages/client/ui/react-ui/src/hooks

useCrossmint

import { useCrossmint } from '@crossmint/client-sdk-react-ui';

const { crossmint, experimental_customAuth } = useCrossmint();

Provides access to the core Crossmint SDK instance.

useAuth

Alias for useCrossmintAuth - see Authentication section.

Type Exports

Key TypeScript types exported from the SDK:

import type {
  // Auth types
  LoginMethod,
  SDKExternalUser,
  OAuthProvider,
  
  // Config types
  CrossmintConfig,
  CrossmintProviderProps,
  
  // Wallet types
  EVMWallet,
  SolanaWallet,
  StellarWallet,
  Wallet,
  DelegatedSigner,
  
  // Transaction types
  Transaction,
  Signature,
  Activity,
  Balances,
  Chain,
  
  // Event types
  CrossmintEvent,
  CrossmintEventMap,
} from '@crossmint/client-sdk-react-ui';

Next Steps

Auth SDK

Build custom authentication flows

React Native SDK

Learn about mobile integration

API Reference

Explore the complete API

Examples

View example applications

Getting Started

Core Concepts

Wallets SDK

Client SDKs

Server SDK

Guides

Examples

​Installation

​Setup

​Provider Props

​Authentication

​CrossmintAuthProvider

​Props

​useCrossmintAuth Hook

​Return Values

​EmbeddedAuthForm Component

​Wallet Management

​CrossmintWalletProvider

​Props

​useWallet Hook

​Return Values

​ExportPrivateKeyButton

​Checkout Components

​CrossmintEmbeddedCheckout

​Props

​CrossmintHostedCheckout

​useCrossmintCheckout Hook

​NFT Display Components

​CrossmintNFTCollectionView

​CrossmintNFTDetail

​Payment Management

​CrossmintPaymentMethodManagement

​Hooks Reference

​useCrossmint

​useAuth

​Type Exports

​Next Steps

Auth SDK

React Native SDK

API Reference

Examples

Build docs developers (and LLMs) love

Installation

Setup

Provider Props

Authentication

CrossmintAuthProvider

Props

useCrossmintAuth Hook

Return Values

EmbeddedAuthForm Component

Wallet Management

CrossmintWalletProvider

Props

useWallet Hook

Return Values

ExportPrivateKeyButton

Checkout Components

CrossmintEmbeddedCheckout

Props

CrossmintHostedCheckout

useCrossmintCheckout Hook

NFT Display Components

CrossmintNFTCollectionView

CrossmintNFTDetail

Payment Management

CrossmintPaymentMethodManagement

Hooks Reference

useCrossmint

useAuth

Type Exports

Next Steps