React Providers

Overview

Crossmint React Providers wrap your application to provide authentication state, wallet functionality, and SDK configuration to all child components.

Installation

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

CrossmintProvider

Root provider that initializes the Crossmint SDK. Required for all other Crossmint components and hooks.

Usage

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

function App() {
  return (
    <CrossmintProvider apiKey="your-api-key">
      {/* Your app */}
    </CrossmintProvider>
  );
}

Props

apiKey

string

required

Your Crossmint API key from the Developer Console

consoleLogLevel

ConsoleLogLevel

default:"debug"

Minimum log level for console output

Show ConsoleLogLevel type

type ConsoleLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'

Example:

// Suppress all console logs
<CrossmintProvider apiKey="..." consoleLogLevel="silent" />

// Show only warnings and errors
<CrossmintProvider apiKey="..." consoleLogLevel="warn" />

children

ReactNode

required

Your application components

Context Value

Provides access via useCrossmint() hook:

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

function MyComponent() {
  const { crossmint } = useCrossmint();
  console.log(crossmint.apiKey);
}

CrossmintAuthProvider

Provides authentication state and UI. Must be nested inside CrossmintProvider.

Usage

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

function App() {
  return (
    <CrossmintProvider apiKey="your-api-key">
      <CrossmintAuthProvider
        loginMethods={['email', 'google', 'farcaster']}
        appearance={{
          colors: {
            accent: '#4F46E5',
            textPrimary: '#000000'
          }
        }}
        onLoginSuccess={() => console.log('Login successful!')}
      >
        {/* Your app */}
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

Props

Authentication methods to enable

Show LoginMethod type

type LoginMethod = 
  | 'email'                  // Email OTP
  | 'google'                 // Google OAuth
  | 'twitter'                // Twitter OAuth
  | 'farcaster'              // Farcaster
  | 'web3-injected'          // Browser wallet (MetaMask, etc.)
  | 'web3-walletconnect'     // WalletConnect
  | 'web3-coinbase'          // Coinbase Wallet

Example:

loginMethods={['email', 'google', 'web3-injected']}

appearance

UIConfig

Customize authentication UI appearance

Show UIConfig properties

colors

object

Show properties

accent

string

Primary accent color (buttons, links)

textPrimary

string

Primary text color

textSecondary

string

Secondary text color

textLink

string

Link color

danger

string

Error/danger color

background

string

Background color

fontFamily

string

Font family for all textExample: "'Inter', sans-serif"

Title displayed in the authentication modal

termsOfServiceText

string | ReactNode

termsOfServiceText={
  <p>
    By signing in, you agree to our{' '}
    <a href="https://example.com/terms">Terms of Service</a> and{' '}
    <a href="https://example.com/privacy">Privacy Policy</a>
  </p>
}

prefetchOAuthUrls

boolean

default:true

Prefetch OAuth URLs for faster login. Set to false to reduce initial load.

Callback invoked after successful loginExample:

onLoginSuccess={() => {
  router.push('/dashboard');
  toast.success('Welcome back!');
}}

refreshRoute

string

Custom server endpoint for refreshing authentication tokens. Required for server-side cookie management.Example (Next.js):

refreshRoute="/api/auth/refresh"

logoutRoute

string

Custom server endpoint for handling logout. Required for server-side cookie management.Example (Next.js):

logoutRoute="/api/auth/logout"

children

ReactNode

required

Your application components

Context Value

Provides access via useCrossmintAuth() hook:

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

function MyComponent() {
  const { user, jwt, status, login, logout } = useCrossmintAuth();
  
  if (status === 'logged-out') {
    return <button onClick={() => login()}>Sign In</button>;
  }
  
  return <p>Welcome, {user?.email}</p>;
}

CrossmintWalletProvider

Provides smart wallet functionality including creation, transactions, and signer management. Must be nested inside CrossmintAuthProvider.

Usage

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

function App() {
  return (
    <CrossmintProvider apiKey="your-api-key">
      <CrossmintAuthProvider loginMethods={['email', 'google']}>
        <CrossmintWalletProvider
          createOnLogin="all-users"
          callbacks={{
            onWalletCreationStart: async () => {
              console.log('Creating wallet...');
            },
            onTransactionStart: async () => {
              console.log('Transaction starting...');
            }
          }}
        >
          {/* Your app */}
        </CrossmintWalletProvider>
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

Props

Automatic wallet creation strategy

Show CreateOnLogin type

type CreateOnLogin = 
  | "all-users"          // Create wallet for all users on login
  | "evm-only"           // Create only EVM wallets
  | "solana-only"        // Create only Solana wallets
  | {
      chains: Array<"evm" | "solana">;
    }

Example:

// Create EVM and Solana wallets
createOnLogin={{ chains: ["evm", "solana"] }}

// Create only EVM wallets
createOnLogin="evm-only"

appearance

UIConfig

Customize wallet UI components (same structure as CrossmintAuthProvider)

showPasskeyHelpers

boolean

default:true

Show passkey helper UI for wallet security

callbacks

object

Lifecycle callbacks for wallet operations

Show properties

onWalletCreationStart

() => Promise<void>

Called before wallet creation beginsExample:

onWalletCreationStart: async () => {
  setLoading(true);
  await trackEvent('wallet_creation_started');
}

onTransactionStart

() => Promise<void>

Called before a transaction is sentExample:

onTransactionStart: async () => {
  showNotification('Preparing transaction...');
}

children

ReactNode

required

Your application components

Context Value

Provides wallet functionality through the Crossmint SDK:

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

function WalletComponent() {
  const { crossmint } = useCrossmint();
  
  const createWallet = async () => {
    const wallet = await crossmint.wallets.create({
      chain: 'ethereum'
    });
    console.log('Wallet created:', wallet.address);
  };
  
  return <button onClick={createWallet}>Create Wallet</button>;
}

Complete Provider Stack

Typical provider hierarchy for a full-featured application:

import {
  CrossmintProvider,
  CrossmintAuthProvider,
  CrossmintWalletProvider,
  useCrossmintAuth
} from '@crossmint/client-sdk-react-ui';

function App() {
  return (
    <CrossmintProvider 
      apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}
      consoleLogLevel="warn"
    >
      <CrossmintAuthProvider
        loginMethods={['email', 'google', 'farcaster', 'web3-injected']}
        appearance={{
          colors: {
            accent: '#4F46E5',
            textPrimary: '#111827',
            textSecondary: '#6B7280'
          },
          fontFamily: "'Inter', sans-serif"
        }}
        authModalTitle="Sign in to MyApp"
        termsOfServiceText={
          <p>
            By signing in, you agree to our{' '}
            <a href="https://example.com/terms">Terms</a>
          </p>
        }
        onLoginSuccess={() => {
          console.log('User logged in');
          router.push('/dashboard');
        }}
        refreshRoute="/api/auth/refresh"
        logoutRoute="/api/auth/logout"
      >
        <CrossmintWalletProvider
          createOnLogin={{ chains: ['evm', 'solana'] }}
          showPasskeyHelpers
          callbacks={{
            onWalletCreationStart: async () => {
              console.log('Creating wallet...');
            },
            onTransactionStart: async () => {
              console.log('Transaction starting...');
            }
          }}
        >
          <Dashboard />
        </CrossmintWalletProvider>
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

function Dashboard() {
  const { user, status, logout } = useCrossmintAuth();
  
  if (status === 'logged-out') {
    return <div>Please sign in</div>;
  }
  
  return (
    <div>
      <h1>Welcome, {user?.email}</h1>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

Provider Requirements

CrossmintProvider is required for all Crossmint functionality
CrossmintAuthProvider is required for useCrossmintAuth() hook
CrossmintWalletProvider requires CrossmintAuthProvider to be present
Providers must be nested in the correct order:

<CrossmintProvider>
  <CrossmintAuthProvider>
    <CrossmintWalletProvider>
      {/* Your app */}
    </CrossmintWalletProvider>
  </CrossmintAuthProvider>
</CrossmintProvider>

Next.js Server-Side Authentication

For Next.js applications with server-side rendering, provide custom routes:

// app/layout.tsx
<CrossmintAuthProvider
  refreshRoute="/api/auth/refresh"
  logoutRoute="/api/auth/logout"
>
  {children}
</CrossmintAuthProvider>

// app/api/auth/refresh/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  // Implement token refresh logic
  // Set secure HTTP-only cookies
  return NextResponse.json({ success: true });
}

// app/api/auth/logout/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  // Clear authentication cookies
  const response = NextResponse.json({ success: true });
  response.cookies.delete('session');
  response.cookies.delete('refresh_token');
  return response;
}

Wallets SDK

Client SDK

Server SDK

Overview

Installation

CrossmintProvider

Usage

Props

Context Value

CrossmintAuthProvider

Usage

Props

Context Value

CrossmintWalletProvider

Usage

Props

Context Value

Complete Provider Stack

Provider Requirements

Next.js Server-Side Authentication

Build docs developers (and LLMs) love

Wallets SDK

Client SDK

Server SDK

​Overview

​Installation

​CrossmintProvider

​Usage

​Props

​Context Value

​CrossmintAuthProvider

​Usage

​Props

​Context Value

​CrossmintWalletProvider

​Usage

​Props

​Context Value

​Complete Provider Stack

​Provider Requirements

​Next.js Server-Side Authentication

Build docs developers (and LLMs) love

Overview

Installation

CrossmintProvider

Usage

Props

Context Value

CrossmintAuthProvider

Usage

Props

Context Value

CrossmintWalletProvider

Usage

Props

Context Value

Complete Provider Stack

Provider Requirements

Next.js Server-Side Authentication