Skip to main content

🚀 React SDK

The Passkeyme React SDK provides inline authentication components that embed directly into your React application, eliminating the need for redirects and giving you complete control over the user experience.

Installation​

npm install @passkeyme/react-auth
# or
yarn add @passkeyme/react-auth
# or
pnpm add @passkeyme/react-auth

Quick Start​

The PasskeymeAuthPanel component provides a complete authentication experience with passkeys, OAuth, and password support:

import { PasskeymeAuthPanel } from '@passkeyme/react-auth';

function App() {
  const handleAuthSuccess = (user, method) => {
    console.log(`User authenticated via ${method}:`, user);
    // Store user state, redirect, etc.
  };

  const handleError = (error) => {
    console.error('Auth error:', error);
  };

  return (
    <div className="app">
      <h1>Welcome to My App</h1>
      <PasskeymeAuthPanel
        providers={['google', 'github']}
        onSuccess={handleAuthSuccess}
        onError={handleError}
        theme={{ container: { backgroundColor: '#ffffff' } }}
        layout="vertical"
      />
    </div>
  );
}

PasskeymeAuthPanel Component​

The primary component for adding authentication to your React app.

Props​

PropTypeRequiredDescription
providersstring[]Enabled OAuth providers (e.g., ['google', 'github'])
onSuccess(user: User, method: string) => void✅Called when authentication succeeds
onError(error: Error) => voidCalled when authentication fails
themePasskeymeAuthPanelThemeCustom theme object
layout'vertical' | 'horizontal' | 'grid'Component layout style (default: 'vertical')
enablePasskeysbooleanEnable passkey authentication (default: true)
titlestringPanel title
subtitlestringPanel subtitle
passkeyButtonTextstringPasskey button text
dividerTextstringDivider text between auth methods
classNamestringAdditional CSS class names

Basic Usage​

import { PasskeymeAuthPanel } from '@passkeyme/react-auth';

function LoginPage() {
  return (
    <PasskeymeAuthPanel
      providers={['google', 'github']}
      onSuccess={(user, method) => {
        // Handle successful authentication
        console.log(`Authenticated via ${method}:`, user);
        localStorage.setItem('user', JSON.stringify(user));
        window.location.href = '/dashboard';
      }}
      onError={(error) => {
        alert(`Authentication failed: ${error.message}`);
      }}
    />
  );
}

Theming and Customization​

Built-in Themes​

// Light theme (uses default theme)
<PasskeymeAuthPanel 
  theme={{
    container: { backgroundColor: '#ffffff' },
    title: { color: '#111827' }
  }} 
/>

// Dark theme  
<PasskeymeAuthPanel 
  theme={{
    container: { backgroundColor: '#1f2937', color: '#ffffff' },
    title: { color: '#ffffff' },
    passkeyButton: { backgroundColor: '#7c3aed' }
  }} 
/>

// Auto theme based on system preference
<PasskeymeAuthPanel className="auto-theme" />

Custom Styling​

<PasskeymeAuthPanel
  theme={{
    container: {
      borderRadius: '12px',
      boxShadow: '0 4px 12px rgba(0,0,0,0.1)',
      padding: '2rem',
      backgroundColor: '#ffffff'
    },
    passkeyButton: {
      borderRadius: '8px',
      fontSize: '16px',
      backgroundColor: '#7c3aed',
      backgroundColorHover: '#6d28d9'
    },
    title: {
      fontSize: '24px',
      color: '#111827'
    }
  }}
/>

CSS Classes​

<PasskeymeAuthPanel
  className="my-auth-panel"
/>
.my-auth-panel {
  max-width: 400px;
  margin: 0 auto;
}

.my-auth-panel .passkeyme-button {
  background: linear-gradient(45deg, #6366f1, #8b5cf6);
}

Layout Options​

Vertical Layout (Default)​

<PasskeymeAuthPanel layout="vertical" />

Creates a vertical stack of authentication options.

Horizontal Layout​

<PasskeymeAuthPanel layout="horizontal" />

Renders authentication options in a horizontal row.

Grid Layout​

<PasskeymeAuthPanel layout="grid" />

Uses a flexible grid layout for OAuth providers.

Spacing Options​

<PasskeymeAuthPanel 
  layout="vertical"
  spacing="compact"    // "compact" | "normal" | "relaxed"
/>

Authentication Providers​

OAuth Providers​

<PasskeymeAuthPanel
  providers={['google', 'github', 'microsoft', 'apple', 'facebook']}
/>

Available providers:

  • google - Google OAuth
  • github - GitHub OAuth
  • microsoft - Microsoft OAuth
  • apple - Apple Sign In
  • facebook - Facebook OAuth

Disable Passkey Authentication​

<PasskeymeAuthPanel
  enablePasskeys={false}
  providers={['google', 'github']}
/>

Event Handling​

Success Event​

const handleAuthSuccess = (user) => {
  console.log('Authenticated user:', {
    id: user.id,
    email: user.email,
    name: user.name,
    picture: user.picture,
    provider: user.provider,
    createdAt: user.createdAt,
    lastLoginAt: user.lastLoginAt
  });
  
  // Store authentication state
  setUser(user);
  
  // Redirect to protected area
  navigate('/dashboard');
};

<PasskeymeAuthPanel
  onSuccess={handleAuthSuccess}
/>

Error Handling​

const handleAuthError = (error) => {
  console.error('Authentication error:', error);
  
  switch (error.code) {
    case 'USER_CANCELLED':
      // User cancelled authentication
      break;
    case 'PASSKEY_NOT_SUPPORTED':
      // Device doesn't support passkeys
      showToast('Passkeys not supported on this device');
      break;
    case 'NETWORK_ERROR':
      // Network connectivity issue
      showToast('Please check your internet connection');
      break;
    default:
      showToast('Authentication failed. Please try again.');
  }
};

<PasskeymeAuthPanel
  onError={handleAuthError}
/>

Advanced Usage​

Conditional Rendering​

function AuthenticatedApp() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Check for existing authentication
    const savedUser = localStorage.getItem('user');
    if (savedUser) {
      setUser(JSON.parse(savedUser));
    }
    setLoading(false);
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (!user) {
    return (
      <PasskeymeAuthPanel
        providers={['google', 'github']}
        onSuccess={(user, method) => {
          setUser(user);
          localStorage.setItem('user', JSON.stringify(user));
        }}
      />
    );
  }

  return (
    <div>
      <h1>Welcome, {user.name}!</h1>
      <button onClick={() => {
        setUser(null);
        localStorage.removeItem('user');
      }}>
        Logout
      </button>
    </div>
  );
}

Integration with State Management​

// Redux
import { useDispatch } from 'react-redux';
import { setUser } from './authSlice';

function LoginComponent() {
  const dispatch = useDispatch();

  return (
    <PasskeymeAuthPanel
      onSuccess={(user) => dispatch(setUser(user))}
    />
  );
}
// Context API
import { useAuth } from './AuthContext';

function LoginComponent() {
  const { login } = useAuth();

  return (
    <PasskeymeAuthPanel
      onSuccess={login}
    />
  );
}

TypeScript Support​

The React SDK includes full TypeScript definitions:

import { PasskeymeAuthPanel, PasskeymeAuthPanelProps } from '@passkeyme/react-auth';

interface Props {
  onComplete: (user: any) => void;
}

const LoginForm: React.FC<Props> = ({ onComplete }) => {
  const handleSuccess = (user: any, method: string) => {
    console.log(`User authenticated via ${method}:`, user);
    onComplete(user);
  };

  const handleError = (error: Error) => {
    console.error('Auth error:', error.message);
  };

  return (
    <PasskeymeAuthPanel
      providers={['google', 'github']}
      onSuccess={handleSuccess}
      onError={handleError}
      theme={{
        container: { backgroundColor: '#ffffff' }
      }}
    />
  );
};

Migration from Hosted Pages​

If you're migrating from hosted authentication pages:

// Before (hosted pages)
import { PasskeymeAuth } from '@passkeyme/auth';

const auth = new PasskeymeAuth({ appId: 'your-app-id' });
auth.redirectToLogin();

// After (inline components)
import { PasskeymeAuthPanel } from '@passkeyme/react-auth';

<PasskeymeAuthPanel
  appId="your-app-id"
  onSuccess={(user, method) => handleLogin(user, method)}
/>

Best Practices​

User Experience​

  • Use custom theme objects to match your app's design
  • Provide clear error messages with onError handler
  • Show loading states during authentication

Security​

  • Never store sensitive user data in localStorage for production apps
  • Implement proper session management
  • Use HTTPS in production

Performance​

  • Lazy load the auth panel if not immediately needed
  • Consider using React.Suspense for component loading
  • Cache user state appropriately

Next Steps​