@zytehub/auth-react

React UI components for ZyteHub Authentication Service. Pre-built, customizable components for authentication flows.

Installation

npm install @zytehub/auth-react @zytehub/auth-client react react-dom

Peer Dependencies: Requires @zytehub/auth-client, react, and react-dom.

Quick Start

import { LoginForm, TwoFactorAuth } from '@zytehub/auth-react';
import { useState } from 'react';

function LoginPage() {
  const [show2FA, setShow2FA] = useState(false);
  const [username, setUsername] = useState('');

  return (
    <div>
      {!show2FA ? (
        <LoginForm
          apiUrl={window.location.origin}
          platformId="my-platform"
          onLoginSuccess={(result) => {
            console.log('Login successful!', result);
            // Redirect to dashboard
          }}
          onNeed2FA={(result, username) => {
            setUsername(username);
            setShow2FA(true);
          }}
          onLoginError={(error) => {
            console.error('Login failed:', error);
          }}
        />
      ) : (
        <TwoFactorAuth
          apiUrl={window.location.origin}
          platformId="my-platform"
          username={username}
          onVerifySuccess={(result) => {
            console.log('2FA verified!', result);
            // Redirect to dashboard
          }}
          onVerifyError={(error) => {
            console.error('2FA failed:', error);
          }}
        />
      )}
    </div>
  );
}

Styling

Components include default styles. Import them:

import { defaultStyles } from '@zytehub/auth-react';

// Add to your app
<style dangerouslySetInnerHTML={{ __html: defaultStyles }} />

Or use your own CSS by targeting the component classes (see Customization).

Components

LoginForm

Email/username and password login form with 2FA support.

<LoginForm
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onLoginSuccess={(result) => {
    // Handle successful login
    // result.access, result.refresh, result.user
  }}
  onNeed2FA={(result, username) => {
    // 2FA required - show TwoFactorAuth component
  }}
  onLoginError={(error) => {
    // Handle login error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier for tracking
• onLoginSuccess (function) - Callback on successful login
• onNeed2FA (function) - Callback when 2FA is required
• onLoginError (function) - Callback on login error

TwoFactorAuth

OTP verification component for 2FA.

<TwoFactorAuth
  apiUrl="https://api.example.com"
  platformId="my-platform"
  username="[email protected]"
  onVerifySuccess={(result) => {
    // 2FA verified successfully
  }}
  onVerifyError={(error) => {
    // Handle verification error
  }}
  onUseBackupCode={() => {
    // Show backup code input
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• username (string, required) - Username from login
• onVerifySuccess (function) - Callback on successful verification
• onVerifyError (function) - Callback on verification error
• onUseBackupCode (function) - Callback to show backup code input

PasswordReset

Request and confirm password reset.

// Request reset (no token)
<PasswordReset
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onResetSuccess={(result) => {
    // Email sent successfully
  }}
  onResetError={(error) => {
    // Handle error
  }}
/>

// Confirm reset (with token from email)
<PasswordReset
  apiUrl="https://api.example.com"
  platformId="my-platform"
  resetToken="token-from-email"
  onResetSuccess={(result) => {
    // Password reset successful
  }}
  onResetError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• resetToken (string, optional) - Token from reset email (shows confirm form)
• onResetSuccess (function) - Callback on success
• onResetError (function) - Callback on error

TwoFactorSetup

Setup, enable, and disable 2FA.

<TwoFactorSetup
  apiUrl="https://api.example.com"
  platformId="my-platform"
  isEnabled={false} // Current 2FA status
  onSetupComplete={() => {
    // 2FA enabled successfully
  }}
  onDisableComplete={() => {
    // 2FA disabled successfully
  }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• isEnabled (boolean) - Current 2FA status
• onSetupComplete (function) - Callback when 2FA is enabled
• onDisableComplete (function) - Callback when 2FA is disabled
• onError (function) - Callback on error

ProfileSettings

View and update user profile information.

<ProfileSettings
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onUpdateSuccess={(profile) => {
    // Profile updated successfully
  }}
  onUpdateError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• onUpdateSuccess (function) - Callback on successful update
• onUpdateError (function) - Callback on error

PasswordChange

Change password (authenticated users).

<PasswordChange
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onSuccess={() => {
    // Password changed successfully
  }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• onSuccess (function) - Callback on success
• onError (function) - Callback on error

SessionManager

View and manage active user sessions.

<SessionManager
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onLogoutAll={() => {
    // All sessions logged out
    // Redirect to login
  }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• onLogoutAll (function) - Callback when all sessions are logged out
• onError (function) - Callback on error

TrustedDevicesManager

Manage trusted devices.

<TrustedDevicesManager
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onDeviceRemoved={() => {
    // Device removed successfully
  }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• onDeviceRemoved (function) - Callback when device is removed
• onError (function) - Callback on error

AuditLogViewer

View security audit logs.

<AuditLogViewer
  apiUrl="https://api.example.com"
  platformId="my-platform"
  filters={{ limit: 50, event_type: 'login_success' }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• filters (object, optional) - Filter options (limit, offset, event_type)
• onError (function) - Callback on error

AccountDeletion

Request account deletion (GDPR compliance).

<AccountDeletion
  apiUrl="https://api.example.com"
  platformId="my-platform"
  onSuccess={() => {
    // Account deletion requested
  }}
  onError={(error) => {
    // Handle error
  }}
/>

Props:

• apiUrl (string, required) - Backend API URL
• platformId (string, required) - Platform identifier
• onSuccess (function) - Callback on success
• onError (function) - Callback on error

Complete Example

import { useState } from 'react';
import {
  LoginForm,
  TwoFactorAuth,
  PasswordReset,
  ProfileSettings,
  SessionManager,
  TwoFactorSetup
} from '@zytehub/auth-react';
import { defaultStyles } from '@zytehub/auth-react';

function App() {
  const [view, setView] = useState('login');
  const [username, setUsername] = useState('');
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  return (
    <div>
      <style dangerouslySetInnerHTML={{ __html: defaultStyles }} />
      
      {!isAuthenticated ? (
        <>
          {view === 'login' && (
            <LoginForm
              apiUrl={window.location.origin}
              platformId="my-platform"
              onLoginSuccess={(result) => {
                setIsAuthenticated(true);
                setView('profile');
              }}
              onNeed2FA={(result, username) => {
                setUsername(username);
                setView('2fa');
              }}
              onLoginError={(error) => {
                alert('Login failed: ' + error.message);
              }}
            />
          )}
          
          {view === '2fa' && (
            <TwoFactorAuth
              apiUrl={window.location.origin}
              platformId="my-platform"
              username={username}
              onVerifySuccess={(result) => {
                setIsAuthenticated(true);
                setView('profile');
              }}
              onVerifyError={(error) => {
                alert('2FA failed: ' + error.message);
              }}
            />
          )}
          
          {view === 'reset' && (
            <PasswordReset
              apiUrl={window.location.origin}
              platformId="my-platform"
              onResetSuccess={() => {
                alert('Reset email sent!');
                setView('login');
              }}
            />
          )}
          
          <button onClick={() => setView('reset')}>
            Forgot Password?
          </button>
        </>
      ) : (
        <>
          <nav>
            <button onClick={() => setView('profile')}>Profile</button>
            <button onClick={() => setView('sessions')}>Sessions</button>
            <button onClick={() => setView('2fa-setup')}>2FA</button>
          </nav>
          
          {view === 'profile' && (
            <ProfileSettings
              apiUrl={window.location.origin}
              platformId="my-platform"
            />
          )}
          
          {view === 'sessions' && (
            <SessionManager
              apiUrl={window.location.origin}
              platformId="my-platform"
              onLogoutAll={() => {
                setIsAuthenticated(false);
                setView('login');
              }}
            />
          )}
          
          {view === '2fa-setup' && (
            <TwoFactorSetup
              apiUrl={window.location.origin}
              platformId="my-platform"
              isEnabled={false}
            />
          )}
        </>
      )}
    </div>
  );
}

Customization

All components use CSS classes that you can override:

CSS Classes

• .auth-login-form, .auth-2fa-form, .auth-password-reset - Container classes
• .auth-error - Error message styling
• .auth-success - Success message styling
• .form-group - Form field container
• .form-group label - Label styling
• .form-group input - Input field styling
• .btn-primary - Primary button
• .btn-secondary - Secondary button
• .otp-input - OTP code input (large, centered)

Example: Custom Styling

/* Override default styles */
.auth-login-form {
  max-width: 500px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.btn-primary {
  background-color: #ff6b6b;
  border-radius: 25px;
}

.btn-primary:hover {
  background-color: #ee5a5a;
}

Platform ID

Critical: Always set platformId on all components. This ensures:

• Proper usage tracking
• Platform-specific analytics
• Security audit logs attribution

// ✅ Correct
<LoginForm
  apiUrl={window.location.origin}
  platformId="fireglue" // Your platform identifier
/>

// ❌ Incorrect - no tracking
<LoginForm
  apiUrl={window.location.origin}
  // Missing platformId!
/>

Error Handling

All components handle errors internally and call error callbacks. Always provide error handlers:

<LoginForm
  apiUrl={window.location.origin}
  platformId="my-platform"
  onLoginError={(error) => {
    // Handle different error types
    if (error.message.includes('Invalid credentials')) {
      setError('Wrong username or password');
    } else if (error.message.includes('Account locked')) {
      setError('Account locked. Please try again later.');
    } else {
      setError('An unexpected error occurred');
    }
  }}
/>

TypeScript Support

TypeScript definitions are included. Import types:

import { LoginForm } from '@zytehub/auth-react';

// Types are automatically inferred from props

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requires React 18+ or React 19+.

License

MIT

Support

For issues and questions:

• GitHub: https://github.com/zytehub/auth-react
• Documentation: https://docs.zytehub.com/auth/react