Authentication Components

This document covers the reusable React components for authentication and authorization in the BuildAppsWith platform. These components handle common auth UI patterns such as sign-in forms, protected routes, and role-based UI elements.

Form Components

SignInForm

A complete sign-in form component with validation and error handling.

import { SignInForm } from '@/components/auth/sign-in-form';

// Basic usage
<SignInForm />

// With custom redirect
<SignInForm redirectTo="/dashboard" />

// With custom appearance
<SignInForm appearance="modal" className="p-6 rounded-lg shadow-lg" />

Props

Prop	Type	Default	Description
`redirectTo`	`string`	`'/'`	Path to redirect after successful sign-in
`appearance`	`'default' \| 'minimal' \| 'modal'`	`'default'`	Visual style of the form
`onSuccess`	`(userId: string) => void`	`undefined`	Callback after successful sign-in
`onError`	`(error: string) => void`	`undefined`	Callback after sign-in error
`className`	`string`	`''`	Additional CSS classes

SignUpForm

A complete sign-up form component with validation and error handling.

import { SignUpForm } from '@/components/auth/sign-up-form';

// Basic usage
<SignUpForm />

// With custom redirect
<SignUpForm redirectTo="/onboarding" />

// With custom appearance
<SignUpForm appearance="minimal" className="max-w-md mx-auto" />

Props

Prop	Type	Default	Description
`redirectTo`	`string`	`'/'`	Path to redirect after successful sign-up
`appearance`	`'default' \| 'minimal' \| 'modal'`	`'default'`	Visual style of the form
`onSuccess`	`(userId: string) => void`	`undefined`	Callback after successful sign-up
`onError`	`(error: string) => void`	`undefined`	Callback after sign-up error
`className`	`string`	`''`	Additional CSS classes

ForgotPasswordForm

A form component for requesting password reset emails.

import { ForgotPasswordForm } from '@/components/auth/forgot-password-form';

// Basic usage
<ForgotPasswordForm />

// With custom appearance
<ForgotPasswordForm appearance="minimal" />

Props

Prop	Type	Default	Description
`appearance`	`'default' \| 'minimal' \| 'modal'`	`'default'`	Visual style of the form
`onSuccess`	`() => void`	`undefined`	Callback after successful submission
`onError`	`(error: string) => void`	`undefined`	Callback after error
`className`	`string`	`''`	Additional CSS classes

Protection Components

ProtectedRoute

A component wrapper that ensures routes are only accessible to authenticated users.

import { ProtectedRoute } from '@/components/auth/protected-route';

// Basic usage - redirects to /login if not authenticated
<ProtectedRoute>
  <DashboardContent />
</ProtectedRoute>

// With custom redirect
<ProtectedRoute redirectTo="/sign-in?from=dashboard">
  <DashboardContent />
</ProtectedRoute>

// With role requirement
<ProtectedRoute requiredRole="ADMIN">
  <AdminDashboard />
</ProtectedRoute>

Props

Prop	Type	Default	Description
`children`	`ReactNode`	Required	Content to show for authenticated users
`redirectTo`	`string`	`'/login'`	Path to redirect unauthenticated users
`requiredRole`	`UserRole`	`undefined`	Required role (optional)
`requiredPermission`	`Permission`	`undefined`	Required permission (optional)
`fallback`	`ReactNode`	`null`	Content to show during auth loading

RoleGate

A component to conditionally render content based on user roles.

import { RoleGate } from '@/components/auth/role-gate';
import { UserRole } from '@/lib/auth/types';

// Only show content for admins
<RoleGate allowedRole={UserRole.ADMIN}>
  <AdminPanel />
</RoleGate>

// With fallback content for other users
<RoleGate 
  allowedRole={UserRole.BUILDER}
  fallback={<p>You need to be a verified builder to access this content.</p>}
>
  <BuilderTools />
</RoleGate>

Props

Prop	Type	Default	Description
`children`	`ReactNode`	Required	Content to show for users with the allowed role
`allowedRole`	`UserRole`	Required	Required role to see the content
`fallback`	`ReactNode`	`null`	Content to show for users without the role

PermissionGate

A component to conditionally render content based on user permissions.

import { PermissionGate } from '@/components/auth/permission-gate';
import { Permission } from '@/lib/auth/types';

// Only show content for users with moderation permission
<PermissionGate requiredPermission={Permission.MODERATE_CONTENT}>
  <ModerationTools />
</PermissionGate>

// With fallback content
<PermissionGate 
  requiredPermission={Permission.CREATE_PROJECT}
  fallback={<RequestAccessButton />}
>
  <CreateProjectForm />
</PermissionGate>

Props

Prop	Type	Default	Description
`children`	`ReactNode`	Required	Content to show for users with the permission
`requiredPermission`	`Permission`	Required	Required permission to see the content
`fallback`	`ReactNode`	`null`	Content to show for users without the permission

User Interface Components

UserAvatar

Displays a user’s avatar with authentication state handling.

import { UserAvatar } from '@/components/auth/user-avatar';

// Basic usage
<UserAvatar />

// With custom size
<UserAvatar size="lg" />

// With fallback for unauthenticated users
<UserAvatar fallback={<GuestAvatar />} />

Props

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of the avatar
`fallback`	`ReactNode`	`<DefaultAvatar />`	Content to show for unauthenticated users
`className`	`string`	`''`	Additional CSS classes

UserProfile

Displays user profile information with authentication state handling.

import { UserProfile } from '@/components/auth/user-profile';

// Basic usage
<UserProfile />

// With custom appearance
<UserProfile appearance="card" />

// With sign-out button
<UserProfile withSignOut={true} />

Props

Prop	Type	Default	Description
`appearance`	`'default' \| 'compact' \| 'card'`	`'default'`	Visual style of the profile
`withSignOut`	`boolean`	`false`	Whether to show sign-out button
`className`	`string`	`''`	Additional CSS classes

SignOutButton

A button to sign out the current user.

import { SignOutButton } from '@/components/auth/sign-out-button';

// Basic usage
<SignOutButton />

// With custom redirect
<SignOutButton redirectTo="/login" />

// With custom label and styling
<SignOutButton 
  label="Logout" 
  className="bg-red-500 text-white" 
/>

Props

Prop	Type	Default	Description
`redirectTo`	`string`	`'/'`	Path to redirect after sign-out
`label`	`string`	`'Sign Out'`	Button label
`onClick`	`() => void`	`undefined`	Additional click handler
`className`	`string`	`''`	Additional CSS classes

Status Components

AuthStatus

Displays the current authentication status.

import { AuthStatus } from '@/components/auth/auth-status';

// Basic usage
<AuthStatus />

// With custom appearance
<AuthStatus appearance="compact" />

Props

Prop	Type	Default	Description
`appearance`	`'default' \| 'compact' \| 'text'`	`'default'`	Visual style of the status
`className`	`string`	`''`	Additional CSS classes

Message Components

AuthError

Displays authentication error messages.

import { AuthError } from '@/components/auth/auth-error';

// With error message
<AuthError message="Invalid email or password" />

// With error code
<AuthError code="invalid_credentials" />

Props

Prop	Type	Default	Description
`message`	`string`	`''`	Error message to display
`code`	`string`	`''`	Error code (translates to a message)
`className`	`string`	`''`	Additional CSS classes

AuthSuccess

Displays authentication success messages.

import { AuthSuccess } from '@/components/auth/auth-success';

// With success message
<AuthSuccess message="Successfully signed in" />

Props

Prop	Type	Default	Description
`message`	`string`	`''`	Success message to display
`className`	`string`	`''`	Additional CSS classes

Implementation Examples

Complete Authentication Page

import { SignInForm } from '@/components/auth/sign-in-form';
import { AuthTabs } from '@/components/auth/auth-tabs';
import { SignUpForm } from '@/components/auth/sign-up-form';
import { ForgotPasswordForm } from '@/components/auth/forgot-password-form';
import { useSearchParams } from 'next/navigation';

function AuthPage() {
  const searchParams = useSearchParams();
  const tab = searchParams.get('tab') || 'sign-in';
  const redirectTo = searchParams.get('redirectTo') || '/dashboard';
  
  return (
    <div className="max-w-md mx-auto py-12">
      <h1 className="text-3xl font-bold mb-8 text-center">
        Welcome to BuildAppsWith
      </h1>
      
      <AuthTabs 
        defaultTab={tab} 
        tabs={[
          {
            id: 'sign-in',
            label: 'Sign In',
            content: <SignInForm redirectTo={redirectTo} />
          },
          {
            id: 'sign-up',
            label: 'Sign Up',
            content: <SignUpForm redirectTo={redirectTo} />
          },
          {
            id: 'forgot-password',
            label: 'Forgot Password',
            content: <ForgotPasswordForm />
          }
        ]}
      />
    </div>
  );
}

Protected Dashboard

import { ProtectedRoute } from '@/components/auth/protected-route';
import { UserProfile } from '@/components/auth/user-profile';
import { RoleGate } from '@/components/auth/role-gate';
import { UserRole } from '@/lib/auth/types';

function Dashboard() {
  return (
    <ProtectedRoute>
      <div className="container mx-auto py-8">
        <div className="flex justify-between items-center mb-8">
          <h1 className="text-3xl font-bold">Dashboard</h1>
          <UserProfile withSignOut={true} />
        </div>
        
        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
          {/* Standard user content */}
          <DashboardCard title="Your Projects" />
          <DashboardCard title="Recent Activity" />
          <DashboardCard title="Notifications" />
          
          {/* Builder-specific content */}
          <RoleGate allowedRole={UserRole.BUILDER}>
            <DashboardCard title="Builder Requests" className="col-span-3" />
          </RoleGate>
          
          {/* Admin-specific content */}
          <RoleGate allowedRole={UserRole.ADMIN}>
            <DashboardCard title="Admin Panel" className="col-span-3 bg-purple-50" />
          </RoleGate>
        </div>
      </div>
    </ProtectedRoute>
  );
}

import { useAuth } from '@/lib/auth/hooks';
import { SignOutButton } from '@/components/auth/sign-out-button';
import { RoleGate } from '@/components/auth/role-gate';
import { UserRole } from '@/lib/auth/types';

function Navigation() {
  const { isAuthenticated } = useAuth();
  
  return (
    <nav className="bg-white shadow">
      <div className="container mx-auto px-4">
        <div className="flex justify-between h-16">
          <div className="flex">
            <a href="/" className="flex-shrink-0 flex items-center">
              BuildAppsWith
            </a>
            <div className="hidden sm:ml-6 sm:flex sm:space-x-8">
              <a href="/" className="nav-link">Home</a>
              <a href="/marketplace" className="nav-link">Marketplace</a>
              
              {/* Authenticated links */}
              {isAuthenticated && (
                <>
                  <a href="/dashboard" className="nav-link">Dashboard</a>
                  <a href="/projects" className="nav-link">Projects</a>
                </>
              )}
              
              {/* Role-specific links */}
              <RoleGate allowedRole={UserRole.BUILDER}>
                <a href="/builder-profile" className="nav-link">
                  Builder Profile
                </a>
              </RoleGate>
              
              <RoleGate allowedRole={UserRole.ADMIN}>
                <a href="/admin" className="nav-link">
                  Admin
                </a>
              </RoleGate>
            </div>
          </div>
          
          <div className="flex items-center">
            {isAuthenticated ? (
              <SignOutButton />
            ) : (
              <a href="/login" className="btn-primary">
                Sign In
              </a>
            )}
          </div>
        </div>
      </div>
    </nav>
  );
}

Best Practices

Use composition for complex auth UIs - Combine smaller components
Always handle loading states - Show skeletons or spinners during auth checks
Provide meaningful fallbacks - Show helpful messages when access is denied
Use typed props - Leverage TypeScript for component props
Maintain accessibility - Ensure all auth components are accessible

Authentication Components

Authentication Components

Form Components

SignInForm

Props

SignUpForm

Props

ForgotPasswordForm

Props

Protection Components

ProtectedRoute

Props

RoleGate

Props

PermissionGate

Props

User Interface Components

UserAvatar

Props

UserProfile

Props

SignOutButton

Props

Status Components

AuthStatus

Props

Message Components

AuthError

Props

AuthSuccess

Props

Implementation Examples

Complete Authentication Page

Protected Dashboard

Navigation with Auth-Aware Links

Best Practices

See Also

​Authentication Components

​Form Components

​SignInForm

​Props

​SignUpForm

​Props

​ForgotPasswordForm

​Props

​Protection Components

​ProtectedRoute

​Props

​RoleGate

​Props

​PermissionGate

​Props

​User Interface Components

​UserAvatar

​Props

​UserProfile

​Props

​SignOutButton

​Props

​Status Components

​AuthStatus

​Props

​Message Components

​AuthError

​Props

​AuthSuccess

​Props

​Implementation Examples

​Complete Authentication Page

​Protected Dashboard

​Navigation with Auth-Aware Links

​Best Practices

​See Also

Authentication Components

Form Components

SignInForm

Props

SignUpForm

Props

ForgotPasswordForm

Props

Protection Components

ProtectedRoute

Props

RoleGate

Props

PermissionGate

Props

User Interface Components

UserAvatar

Props

UserProfile

Props

SignOutButton

Props

Status Components

AuthStatus

Props

Message Components

AuthError

Props

AuthSuccess

Props

Implementation Examples

Complete Authentication Page

Protected Dashboard

Navigation with Auth-Aware Links

Best Practices

See Also