@use-firebase/auth

A custom React Hook that provides a declarative interface for Firebase Auth.

Installation

$ npm i @use-firebase/auth

or

$ yarn add @use-firebase/auth

Usage

The Auth package requires that you install App as a dependency and that you wrap your App in both <FirebaseAppProvider> and <FirebaseAuthProvider> as shown here.

import React from 'react';
import { FirebaseAppProvider } from '@use-firebase/app';
import { FirebaseAuthProvider } from '@use-firebase/auth';

import App from './App';
import config from './data/firebaseConfig';

const FirebaseApp = () => (
  <FirebaseAppProvider config={config}>
    <FirebaseAuthProvider>
      <App />
    </FirebaseAuthProvider>
  </FirebaseAppProvider>
);

export default FirebaseApp;

This provides the global context that useFirebaseAuth needs. Now you can use useFirebaseAuth anywhere in your App.

Initially, you will probably want to display either a Sign In screen if not signed in. You can detect if you are signed in like this.

import { useFirebaseAuth } from '@use-firebase/auth';

const App = () => {
  const { isSignedIn } = useFirebaseAuth();

  return (
    <div className="App">
      {isSignedIn ? <AuthenticatedApp /> : <NonAuthenticatedApp />}
    </div>
  );
};

export default App;

Here we either render the AuthenticatedApp or the NonAuthenticatedApp component. The NonAuthenticatedApp would be where we render the sign in page.

Here's an example sign in page with a button that allows the user to sign in with their Google credentials.

import { useFirebaseAuth, AuthProvider } from '@use-firebase/auth';

const NonAuthenticatedApp = () => {
  const { signIn, signInError, createAuthProvider } = useFirebaseAuth();

  const onSignIn = authProvider => {
    const provider = createAuthProvider(authProvider);
    signIn(provider);
  };

  return (
    <div>
      <h1>Please Sign In</h1>
      <p>
        <button onClick={() => onSignIn(AuthProvider.GOOGLE)}>
          Sign In with Google
        </button>
      </p>
      {signInError && <div className="error-message">
        <h3>{signInError.code}</h3>
        {signInError.message}
      </div>}
    </div>
  );
};

It redirects to the authentication page of the provider—Google in this case. After the user is authenticated, you will be redirected back to your app where isSignedIn will be true and the AuthenticatedApp component will be rendered. If there was an error for any reason, signInError will be non-null.

If you would rather use a popup, instead of a redirect, replace onSignIn with this.

const onSignIn = authProvider => {
  const provider = createAuthProvider(authProvider);
  signIn(provider, { method: 'signInWithPopup' });
};

One the user has been sucessfully authenticated, you will want to display an authenticated experience, Here is a sample AuthenticatedApp component that displayed the user's name and image. It also renders a sign out button.

import { useFirebaseAuth } from '@use-firebase/auth';

const AuthenticatedApp = () => {
  const { user, signOut } = useFirebaseAuth();
  const { displayName, photoURL } = user;

  return (
    <div>
      <h1>Welcome {displayName}</h1>
      <div>
        <img className="avatar" alt={displayName} src={photoURL} />
      </div>
      <p>
        <button onClick={signOut}>Sign Out</button>
      </p>
    </div>
  );
};

You will note that it destructures two things from the call to useFirebaseAuth: user (a user object) and signOut (a function to sign out).

API

An import from @use-firebase/auth provides FirebaseAuthProvider, useFirebaseAuth, and AuthProvider.

FirebaseAuthProvider

You must wrap your App in FirebaseAuthProvider like this.

<FirebaseAuthProvider>
  <App />
</FirebaseAuthProvider>

It provides context for useFirebaseAuth.

useFirebaseAuth

useFirebaseAuth is a custom hook that returns a session object every time that the authentication state changes.

A session object has the following properties.

| Parameter | Description | | :------------------- | :--------------------------------------------------------------------------- | | loading | Set to true if the rest of the session properties are indeterminate. | | isSignedIn | Set to true if the user is signed in. | | user | A user object if signed in, otherwise an empty object. See below. | | signInError | The error from the previous signIn attempt or null if it was a success. | | createAuthProvider | A function that returns a provider instance given an enum AuthProvider value. | | signIn | A function that will take the user on the sign in journey. If successful, isSignedIn will be to false. See below for details. | | signOut | A function that will sign the user out. If successful, isSignedIn will be to false. |

user

user is a user object with the following properties.

| Parameter | Description | | :-------------- | :------------------------------------------------------------------------------------------------------------- | | uid | A unique identifier for the user. | | displayName | The user's full name. | | photoURL | A URL to the user's image. May not be included for all providers. | | email | The user's email address. May not be included for all providers. | | emailVerified | true if the email is verified. | | isAnonymous | true if the authenticaion method was ANONYMOUS. | | phoneNumber | The user's phone number. May not be included for all providers. |

createAuthProvider

Call createAuthProvider with one of the AuthProvider enum values. It returns a provider instance that you can pass to signIn See the Firebase documentation for more information.

signIn

Call signIn with an provider instance and an optional options object.

The options object has a single key of method. method is a string with either signInWithRedirect or signInWithPopup. The default is signInWithRedirect.

signIn returns a promise that will resolve upon a successful sign in (if using a popup) or reject if a sign in could not be performed.

For example, here is a simple SignIn component that allows the user to sign in using their Google credentials.

import { useFirebaseAuth, AuthProvider } from '@use-firebase/auth';

const SignIn = () => {
  const { signIn, createAuthProvider } = useFirebaseAuth();
  const googleProvider = createAuthProvider(AuthProvider.GOOGLE);

  return (
    <button onClick={() => signIn(googleProvider)}>Sign In with Google</button>
  );
};

signOut

Call signOut to sign the user out.

It returns a promise that will resolve upon a successful sign out or reject if a sign out could not be performed.

AuthProvider

AuthProvider is an enum with the following values.

| Parameter | Description | | :---------- | :---------------------------- | | ANONYMOUS | No credentials required. | | GITHUB | Authenticate against GitHub | | GOOGLE | Authenticate against Google. | | FACEBOOK | Authenticate against Facebook | | TWITTER | Authenticate against Twitter |

Live demo

You can run the sign in demo on CodeSandbox where you can see all of the code above. Fork it, change the config data to point to your Firebase project, and make your own app.

License

MIT Licensed