React Firebase Phone Auth

A complete, ready-to-use Firebase phone authentication solution for React apps with minimal setup required.

Features

• 🔥 Firebase Integration - Seamless Firebase Auth integration
• 📱 Complete UI - Beautiful, pre-built phone auth form
• 🌍 Regional Support - Support for Ireland, UK, US, and all European countries
• 🎨 Customizable - Easy styling with CSS classes and inline styles
• 🌙 Dark Mode - Built-in dark mode support
• ♿ Accessible - WCAG compliant and keyboard navigable
• 🔒 Secure - Automatic invisible reCAPTCHA handling, rate limiting, and error handling
• 📦 Lightweight - Small bundle size with tree-shaking support
• 💪 TypeScript - Full TypeScript support with type definitions
• 🎣 Flexible - Use pre-built components or custom UI with hooks

Installation

npm install react-firebase-phone-auth firebase

or

yarn add react-firebase-phone-auth firebase

Quick Start

import { PhoneAuthProvider, PhoneAuthForm } from 'react-firebase-phone-auth';
import 'react-firebase-phone-auth/dist/styles.css';

const firebaseConfig = {
  apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
  authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.REACT_APP_FIREBASE_PROJECT_ID,
};

function App() {
  return (
    <PhoneAuthProvider config={firebaseConfig}>
      <PhoneAuthForm
        onSuccess={(user) => console.log('Authenticated!', user)}
        onError={(error) => console.error(error)}
      />
    </PhoneAuthProvider>
  );
}

export default App;

Note: Firebase Phone Auth requires reCAPTCHA. Make sure to:

1. Enable Phone authentication in Firebase Console
2. Add your domain to authorized domains in Firebase Console
3. See Setup Guide and reCAPTCHA Guide for details

Documentation

• Setup Guide - Complete Firebase setup instructions
• reCAPTCHA Guide - Everything about reCAPTCHA configuration and troubleshooting
• Usage Guide - Detailed usage examples and patterns
• API Reference - Complete API documentation
• Styling Guide - Customization and theming
• Publishing Guide - How to publish to npm
• Examples - Real-world implementation examples

Components

PhoneAuthProvider

Context provider that wraps your app and initializes Firebase.

<PhoneAuthProvider config={firebaseConfig}>
  {/* Your app */}
</PhoneAuthProvider>

PhoneAuthForm

Complete phone authentication form with built-in UI.

<PhoneAuthForm
  onSuccess={(user) => console.log('Success!', user)}
  onError={(error) => console.error(error)}
  onCodeSent={(phoneNumber) => console.log('Code sent to', phoneNumber)}
  defaultCountry="US"
  className="custom-class"
/>

usePhoneAuth Hook

For building custom UI:

import { usePhoneAuth } from 'react-firebase-phone-auth';

function CustomAuthForm() {
  const { sendCode, verifyCode, user, loading, error, signOut } = usePhoneAuth();

  // Build your custom UI
  return (
    <div>
      {/* Your custom form */}
    </div>
  );
}

Props

PhoneAuthProvider

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | FirebaseConfig | Yes | Firebase configuration object | | children | ReactNode | Yes | Child components |

PhoneAuthForm

| Prop | Type | Default | Description | |------|------|---------|-------------| | onSuccess | (user: User) => void | - | Callback when authentication succeeds | | onError | (error: Error) => void | - | Callback when an error occurs | | onCodeSent | (phoneNumber: string) => void | - | Callback when verification code is sent | | className | string | '' | Additional CSS class names | | style | CSSProperties | {} | Inline styles | | defaultCountry | string | 'IE' | Default country code (IE, GB, US, or any EU country) | | autoFocus | boolean | true | Auto focus on phone input |

usePhoneAuth Return Value

| Property | Type | Description | |----------|------|-------------| | user | User | null | Current authenticated user | | loading | boolean | Loading state | | error | Error | null | Current error | | sendCode | (phoneNumber: string) => Promise | Send verification code | | verifyCode | (code: string) => Promise | Verify code and sign in | | signOut | () => Promise | Sign out current user | | clearError | () => void | Clear error state |

Features

Automatic Phone Number Formatting

Phone numbers are automatically formatted to E.164 format required by Firebase.

Country Code Selector

Built-in searchable country selector with support for Ireland, United Kingdom, United States, and all European countries (30+ countries total).

Resend Code

Automatic countdown timer (60 seconds) before allowing code resend.

Error Handling

User-friendly error messages for all Firebase error codes:

• Invalid phone number
• Too many requests
• Invalid verification code
• Network errors
• Firebase quota exceeded

Dark Mode

Automatic dark mode support based on user's system preferences.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Requirements

• React 16.8+ (Hooks support)
• Firebase 9.0+
• Modern browser with ES6 support

License

MIT

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Support

• GitHub Issues
• Documentation

Changelog

See CHANGELOG.md for version history.