@emmanuel-saleem/auth-ui

A comprehensive, customizable authentication UI component library for React and Next.js applications. Built with TypeScript and supports multiple CSS frameworks including Tailwind CSS, Bootstrap, and vanilla CSS.

Features

• 🔐 Complete Auth Flow: Login, Register, Forgot Password, Reset Password
• 🎨 Multiple CSS Frameworks: Tailwind CSS, Bootstrap, and vanilla CSS
• 📱 Responsive Design: Mobile-first approach with responsive layouts
• ♿ Accessibility: ARIA labels, keyboard navigation, screen reader support
• 🔧 Customizable: Publish and customize components easily
• 📝 TypeScript: Full type definitions and type safety
• ✅ Form Validation: Built-in validation with Zod schemas
• 🎯 Social Login: Support for Google, GitHub, Facebook, Twitter
• 🚀 Easy Integration: Works with React and Next.js out of the box

Installation

npm install @emmanuel-saleem/auth-ui

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

Quick Start

Basic Usage

import { LoginForm } from '@emmanuel-saleem/auth-ui';

function LoginPage() {
  const handleLogin = async (data) => {
    // Your authentication logic
    console.log('Login data:', data);
  };

  return (
    <LoginForm 
      onSubmit={handleLogin}
      onForgotPassword={() => console.log('Forgot password')}
    />
  );
}

Publishing Customizable Templates

To publish customizable templates to your project:

# Publish Tailwind CSS templates (default)
npx @emmanuel-saleem/auth-ui publish

# Publish Bootstrap templates
npx @emmanuel-saleem/auth-ui publish --framework=bootstrap

# Publish vanilla CSS templates
npx @emmanuel-saleem/auth-ui publish --framework=vanilla

# Custom output directory
npx @emmanuel-saleem/auth-ui publish --output=./custom-auth

This will create the following structure in your project:

auth-ui/
├── components/
│   ├── LoginForm.tsx
│   ├── RegisterForm.tsx
│   ├── ForgotPasswordForm.tsx
│   └── ResetPasswordForm.tsx
├── styles/
│   └── auth.css (for vanilla CSS)
├── config.ts
└── README.md

Components

LoginForm

import { LoginForm } from '@emmanuel-saleem/auth-ui';

<LoginForm
  onSubmit={(data) => handleLogin(data)}
  onForgotPassword={() => navigate('/forgot-password')}
  redirectTo="/dashboard"
  showRememberMe={true}
  showSocialLogin={true}
  socialProviders={['google', 'github']}
  customStyles={{
    container: 'custom-class',
    button: 'custom-btn-class'
  }}
/>

Props:

• onSubmit: Function to handle login submission
• onForgotPassword?: Function called when "Forgot Password" is clicked
• redirectTo?: URL to redirect after successful login
• showRememberMe?: Show "Remember Me" checkbox (default: true)
• showSocialLogin?: Show social login buttons (default: true)
• socialProviders?: Array of social providers to show
• customStyles?: Custom CSS classes for styling
• isLoading?: External loading state
• error?: External error message

RegisterForm

import { RegisterForm } from '@emmanuel-saleem/auth-ui';

<RegisterForm
  onSubmit={(data) => handleRegister(data)}
  onBackToLogin={() => navigate('/login')}
  showSocialLogin={true}
  socialProviders={['google', 'github']}
/>

Props:

• onSubmit: Function to handle registration submission
• onBackToLogin?: Function called when "Back to Login" is clicked
• showSocialLogin?: Show social login buttons (default: true)
• socialProviders?: Array of social providers to show
• customStyles?: Custom CSS classes for styling
• isLoading?: External loading state
• error?: External error message

ForgotPasswordForm

import { ForgotPasswordForm } from '@emmanuel-saleem/auth-ui';

<ForgotPasswordForm
  onSubmit={(email) => handleForgotPassword(email)}
  onBackToLogin={() => navigate('/login')}
  successMessage="Check your email for reset link"
/>

Props:

• onSubmit: Function to handle forgot password submission
• onBackToLogin?: Function called when "Back to Login" is clicked
• successMessage?: Success message to display
• customStyles?: Custom CSS classes for styling
• isLoading?: External loading state
• error?: External error message

ResetPasswordForm

import { ResetPasswordForm } from '@emmanuel-saleem/auth-ui';

<ResetPasswordForm
  token={token}
  onSubmit={(data) => handleResetPassword(data)}
  onSuccess={() => navigate('/login')}
/>

Props:

• token: Reset token from URL
• onSubmit: Function to handle password reset submission
• onSuccess?: Function called after successful reset
• customStyles?: Custom CSS classes for styling
• isLoading?: External loading state
• error?: External error message

Configuration

Create an auth-ui.config.js file in your project root to customize default behavior:

export default {
  theme: 'tailwind', // or 'bootstrap', 'vanilla'
  pages: {
    login: {
      showSocialLogin: true,
      showRememberMe: true,
      redirectAfterLogin: '/dashboard'
    },
    register: {
      requireEmailVerification: true,
      fields: ['name', 'email', 'password', 'password_confirmation']
    }
  },
  validation: {
    passwordMinLength: 8,
    passwordRequireSpecialChar: true
  },
  styling: {
    primaryColor: '#3b82f6',
    borderRadius: '0.5rem'
  }
}

Styling

Tailwind CSS (Default)

The components use Tailwind CSS classes by default. You can customize the appearance by:

1. Custom Classes: Use the customStyles prop
2. CSS Variables: Override CSS custom properties
3. Tailwind Config: Extend your Tailwind configuration

<LoginForm
  customStyles={{
    container: 'max-w-lg mx-auto',
    button: 'bg-purple-600 hover:bg-purple-700',
    input: 'border-purple-300 focus:border-purple-500'
  }}
/>

Bootstrap

For Bootstrap styling, publish Bootstrap templates:

npx @emmanuel-saleem/auth-ui publish --framework=bootstrap

Make sure to include Bootstrap CSS in your project:

<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">

Vanilla CSS

For vanilla CSS styling, publish vanilla templates:

npx @emmanuel-saleem/auth-ui publish --framework=vanilla

Include the generated CSS file:

import './auth-ui/styles/auth.css';

Customize using CSS variables:

:root {
  --auth-primary-color: #your-color;
  --auth-border-radius: 0.75rem;
  --auth-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}

Form Validation

The package includes built-in validation using Zod schemas:

import { loginSchema, registerSchema } from '@emmanuel-saleem/auth-ui';

// Validation schemas are automatically applied
// Custom validation rules can be added by extending the schemas

Custom Validation

import { z } from 'zod';
import { loginSchema } from '@emmanuel-saleem/auth-ui';

const customLoginSchema = loginSchema.extend({
  email: z.string().email().refine(
    (email) => email.endsWith('@yourcompany.com'),
    'Must use company email'
  )
});

Social Login

Supported social providers:

• Google
• GitHub
• Facebook
• Twitter

<LoginForm
  socialProviders={['google', 'github']}
  onSocialLogin={(provider) => {
    // Handle social login
    window.location.href = `/auth/${provider}`;
  }}
/>

TypeScript Support

The package is built with TypeScript and includes full type definitions:

import type { 
  LoginFormData, 
  RegisterFormData, 
  AuthConfig,
  CustomStyles 
} from '@emmanuel-saleem/auth-ui';

Examples

Next.js App Router

// app/login/page.tsx
'use client';

import { LoginForm } from '@emmanuel-saleem/auth-ui';
import { useRouter } from 'next/navigation';

export default function LoginPage() {
  const router = useRouter();

  const handleLogin = async (data) => {
    try {
      const response = await fetch('/api/auth/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });
      
      if (response.ok) {
        router.push('/dashboard');
      }
    } catch (error) {
      console.error('Login failed:', error);
    }
  };

  return (
    <div className="min-h-screen flex items-center justify-center">
      <LoginForm onSubmit={handleLogin} />
    </div>
  );
}

React with React Router

// LoginPage.tsx
import { LoginForm } from '@emmanuel-saleem/auth-ui';
import { useNavigate } from 'react-router-dom';

export function LoginPage() {
  const navigate = useNavigate();

  const handleLogin = async (data) => {
    // Your authentication logic
    navigate('/dashboard');
  };

  return (
    <div className="login-container">
      <LoginForm 
        onSubmit={handleLogin}
        onForgotPassword={() => navigate('/forgot-password')}
      />
    </div>
  );
}

CLI Commands

Publish Templates

# Basic usage
npx @emmanuel-saleem/auth-ui publish

# With options
npx @emmanuel-saleem/auth-ui publish --framework=bootstrap --output=./auth-components

# Help
npx @emmanuel-saleem/auth-ui publish --help

Options:

• --framework, -f: CSS framework (tailwind, bootstrap, vanilla)
• --output, -o: Output directory for published files
• --help, -h: Show help message

Migration Guide

From Other Auth Libraries

From React Hook Form + Custom Components

// Before
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(loginSchema)
  });
  
  // Custom form implementation...
}

// After
import { LoginForm } from '@emmanuel-saleem/auth-ui';

function LoginPage() {
  return <LoginForm onSubmit={handleLogin} />;
}

From UI Libraries (Material-UI, Ant Design)

// Before
import { TextField, Button } from '@mui/material';

// After
import { LoginForm } from '@emmanuel-saleem/auth-ui';

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Author

Emmanuel Saleem

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Changelog

See CHANGELOG.md for a list of changes and version history.