Skip to main content

​
Overview

The Crossmint React SDK provides hooks for managing authentication state, accessing wallet functionality, and integrating with the Crossmint API.

​
Installation

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

​
useCrossmintAuth

Access authentication state and methods. Alias: useAuth

​
Usage

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

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

  if (status === 'initializing') {
    return <div>Loading...</div>;
  }

  if (status === 'logged-out') {
    return <button onClick={() => login()}>Sign In</button>;
  }

  return (
    <div>
      <p>Welcome, {user?.email}</p>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

​
Return Value

​
user
User | undefined
Current authenticated user
​
jwt
string | undefined
JWT authentication token for the current session
​
status
AuthStatus
Current authentication status
​
login
(defaultEmail?: string) => void
Opens the authentication dialogParameters:
  • defaultEmail (optional): Pre-fill email in the login form
Example:
login('[email protected]');
​
logout
() => Promise<void>
Logs out the current user and clears authentication stateExample:
await logout();
router.push('/login');
​
getUser
() => Promise<User>
Fetches the current user’s information from the APIExample:
const user = await getUser();
console.log(user.email);
​
crossmintAuth
CrossmintAuthClient | undefined
Direct access to the underlying auth client for advanced use cases
​
experimental_loginWithOAuth
(provider: OAuthProvider) => Promise<void>
Programmatically initiate OAuth login without opening the dialogParameters:
  • provider: OAuth provider (‘google’, ‘twitter’, ‘farcaster’, etc.)
Example:
await experimental_loginWithOAuth('google');
​
experimental_externalWalletSigner
ExternalWalletSignerConfigForChain | undefined
Web3 wallet signer configuration when using wallet-based authentication
​
loginMethods
LoginMethod[]
Available login methods configured in the provider

​
Error Handling

const { login, status } = useCrossmintAuth();

try {
  login();
  // Monitor status changes
  if (status === 'logged-in') {
    console.log('Login successful');
  }
} catch (error) {
  console.error('Login failed:', error);
}

​
Requirements

Must be used within <CrossmintAuthProvider>: 
import { 
  CrossmintProvider, 
  CrossmintAuthProvider,
  useCrossmintAuth 
} from '@crossmint/client-sdk-react-ui';

function App() {
  return (
    <CrossmintProvider apiKey="your-api-key">
      <CrossmintAuthProvider loginMethods={['email', 'google']}>
        <ProfilePage />
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

function ProfilePage() {
  const auth = useCrossmintAuth();
  // Use auth methods
}

​
useCrossmint

Access the core Crossmint SDK instance and configuration.

​
Usage

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

function MyComponent() {
  const { crossmint, experimental_customAuth } = useCrossmint();

  console.log('API Key:', crossmint.apiKey);
  console.log('Environment:', crossmint.environment);

  return <div>...</div>;
}

​
Return Value

​
crossmint
Crossmint
Core Crossmint SDK instance
​
experimental_customAuth
CustomAuth | undefined
Custom authentication configuration
​
experimental_setCustomAuth
(auth: CustomAuth | undefined) => void
Update custom authentication state

​
Requirements

Must be used within <CrossmintProvider>: 
import { CrossmintProvider, useCrossmint } from '@crossmint/client-sdk-react-ui';

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

function MyComponent() {
  const { crossmint } = useCrossmint();
  return <div>API Key: {crossmint.apiKey}</div>;
}

​
useEnvironment

Detect the current environment (staging or production) based on the API key.

​
Usage

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

function DebugPanel() {
  const environment = useEnvironment();

  return (
    <div>
      <p>Running in: {environment}</p>
      {environment === 'staging' && (
        <div className="debug-banner">Test Mode</div>
      )}
    </div>
  );
}

​
Return Value

​
environment
'staging' | 'production'
Current environment determined from the Crossmint API key

​
Requirements

Must be used within <CrossmintProvider>.

​
useDeepEffect

Utility hook for deep comparison of effect dependencies (prevents unnecessary re-renders).

​
Usage

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

function MyComponent({ config }) {
  useDeepEffect(() => {
    console.log('Config changed:', config);
    // This only runs when config deeply changes
  }, [config]);

  return <div>...</div>;
}

​
Parameters

​
callback
() => void | (() => void)
required
Effect callback (can return cleanup function)
​
dependencies
any[]
required
Dependency array (performs deep equality check)

​
useOAuthWindowListener

Internal hook for handling OAuth popup window messages (advanced use).

​
Usage

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

function OAuthHandler() {
  useOAuthWindowListener({
    onSuccess: (authData) => {
      console.log('OAuth success:', authData);
    },
    onError: (error) => {
      console.error('OAuth error:', error);
    }
  });

  return <div>Processing OAuth...</div>;
}
This hook is typically used internally by CrossmintAuthProvider. Use experimental_loginWithOAuth from useCrossmintAuth for standard OAuth flows.

​
Complete Example

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

function App() {
  return (
    <CrossmintProvider apiKey="your-api-key">
      <CrossmintAuthProvider 
        loginMethods={['email', 'google', 'farcaster']}
        onLoginSuccess={() => console.log('Login successful!')}
      >
        <Dashboard />
      </CrossmintAuthProvider>
    </CrossmintProvider>
  );
}

function Dashboard() {
  const { user, status, login, logout } = useCrossmintAuth();
  const { crossmint } = useCrossmint();
  const environment = useEnvironment();

  if (status === 'initializing') {
    return <div>Loading...</div>;
  }

  if (status === 'logged-out') {
    return (
      <div>
        <h1>Welcome to Crossmint</h1>
        <button onClick={() => login()}>Sign In</button>
      </div>
    );
  }

  return (
    <div>
      <header>
        <p>Welcome, {user?.email}</p>
        <p>Environment: {environment}</p>
        <button onClick={logout}>Sign Out</button>
      </header>
      <main>
        <h2>Your Dashboard</h2>
        {/* Your app content */}
      </main>
    </div>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us