invertase/react-query-firebaseReact Query Firebase

Authentication Actions

When working with Authentication, it's common you'll want to perform authentication actions throughout your application, such as signing in a user, creating a user, triggering an OAuth flow, updating a user and lots more.

The React Query Firebase library supports all of the authentication actions by wrapping around the useMutation hook.

Although the Firebase SDK makes it super simple to perform these actions, it is still up to you to handle local state such as loading, errors and success. The hooks provided by this library make such scenarios simple.

For example, to sign a user in without the hooks, we need to handle many states ourselves:

import { signInWithEmailAndPassword } from "firebase/auth";
import { auth } from "./firebase";

function SignIn() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [loading, setLoading] = useState("");
  const [error, setError] = useState("");

  async function onSignIn() {
    try {
      setLoading(true);
      await signInWithEmailAndPassword(auth, email, password);
    } catch (e) {
      setError(e.message);
    } finally {
      setLoading(false);
    }
  }

  return (
    <>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <input value={password} onChange={(e) => setPassword(e.target.value)} />
      <button disabled={loading} onClick={onSignIn}>
        Sign In
      </button>
      {!!error && <p>{error}</p>}
    </>
  );
}

Granted this could be cleaned up using form libraries and reducers, however repeating this process for the many authentication actions becomes tiresome.

Instead, with React Query Firebase we're able to quickly setup the same flow with minimal code:

import { useAuthSignInWithEmailAndPassword } from "@react-query-firebase/auth";
import { auth } from "./firebase";

function SignIn() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const mutation = useAuthSignInWithEmailAndPassword(auth, {
    onError(error) {
      toast.error("Could not sign you in!");
    },
  });

  function onSignIn() {
    mutation.mutate({ email, password });
  }

  return (
    <>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <input value={password} onChange={(e) => setPassword(e.target.value)} />
      <button disabled={mutation.isLoading} onClick={onSignIn}>
        Sign In
      </button>
      {mutation.isError && <p>{mutation.error.message}</p>}
    </>
  );
}

By using the built in hooks, we abstract the async state handling to React Query, allowing us to focus building the UI and not local state management. Another bonus is we're able to provide the React Query mutation options to all of the hooks, allowing us to handle side-effects such as error handling!

Hooks

Below is a list of all of the available hooks which wrap the Firebase API.

useAuthApplyActionCode

Applies a verification code sent to the user by email or other out-of-band mechanism.

const mutation = useAuthApplyActionCode(auth);
mutation.mutate("oobCode");

useAuthCheckActionCode

Checks a verification code sent to the user by email or other out-of-band mechanism.

const mutation = useAuthCheckActionCode(auth, {
  onSuccess(actionCodeInfo) {
    console.log("Valid action code!");
  },
  onError(error) {
    console.error("Invalid action code: ", error.code);
  },
});

mutation.mutate("oobCode");

useAuthConfirmPasswordReset

Completes the password reset process, given a confirmation code and new password.

const mutation = useAuthCheckActionCode(auth);

mutation.mutate({
  oobCode: "...",
  newPassword: "...",
});

useAuthCreateUserWithEmailAndPassword

Creates a new user account associated with the specified email address and password.

const mutation = useAuthCreateUserWithEmailAndPassword(auth);

mutation.mutate({
  email: "foo@bar.com",
  password: "...",
});

useAuthDeleteUser

Deletes and signs out the user.

const mutation = useAuthDeleteUser(auth);

mutation.mutate();

useAuthLinkWithCredential

Links the user account with the given credentials.

const mutation = useAuthLinkWithCredential();

mutation.mutate({
  user: auth.currentUser,
  // Any Auth credential supported...
  credential: EmailAuthProvider.credential('foo@bar.com', '...');
});

useAuthLinkWithPhoneNumber

Links the user account with the given phone number.

const mutation = useAuthLinkWithPhoneNumber();

mutation.mutate({
  user: auth.currentUser,
  phoneNumber: '+44123456789'
  appVerifier: new RecaptchaVerifier('recaptcha'),
});

useAuthLinkWithPopup

Links the authenticated provider to the user account using a pop-up based OAuth flow.

const mutation = useAuthLinkWithPopup();

mutation.mutate({
  user: auth.currentUser,
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthLinkWithRedirect

Links the OAuthProvider to the user account using a full-page redirect flow.

const mutation = useAuthLinkWithRedirect();

mutation.mutate({
  user: auth.currentUser,
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthReauthenticateWithCredential

Re-authenticates a user using a fresh credential.

const mutation = useAuthReauthenticateWithCredential();

mutation.mutate({
  user: auth.currentUser,
  // Any Auth credential supported...
  credential: EmailAuthProvider.credential('foo@bar.com', '...');
});

useAuthReauthenticateWithPhoneNumber

Re-authenticates a user using a fresh phone credential.

const mutation = useAuthReauthenticateWithCredential();

mutation.mutate({
  user: auth.currentUser,
  phoneNumber: '+44123456789'
  appVerifier: new RecaptchaVerifier('recaptcha'),
});

useAuthReauthenticateWithPopup

Reauthenticates the current user with the specified OAuthProvider using a pop-up based OAuth flow.

const mutation = useAuthReauthenticateWithPopup();

mutation.mutate({
  user: auth.currentUser,
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthReauthenticateWithRedirect

Reauthenticates the current user with the specified OAuthProvider using a full-page redirect flow.

const mutation = useAuthReauthenticateWithRedirect();

mutation.mutate({
  user: auth.currentUser,
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthReload

Reloads user account data, if signed in.

const mutation = useAuthReload();

mutation.mutate({
  user: auth.currentUser,
});

useAuthSendEmailVerification

Sends a verification email to a user.

const mutation = useAuthSendEmailVerification();

mutation.mutate({
  user: auth.currentUser,
  actionCodeSettings: {...}, // optional
});

useAuthSendPasswordResetEmail

Sends a password reset email to the given email address.

const mutation = useAuthSendPasswordResetEmail(auth);

mutation.mutate({
  email: 'foo@bar.com',
  actionCodeSettings: {...}, // optional
});

useAuthSendSignInLinkToEmail

Sends a sign-in email link to the user with the specified email.

const mutation = useAuthSendPasswordResetEmail(auth);

mutation.mutate({
  email: 'foo@bar.com',
  actionCodeSettings: {...},
});

useAuthSignInAnonymously

Asynchronously signs in as an anonymous user.

const mutation = useAuthSignInAnonymously(auth);

mutation.mutate();

useAuthSignInWithCredential

Asynchronously signs in with the given credentials.

const mutation = useAuthSignInWithCredential(auth);

const credential = EmailAuthProvider.credential("foo@bar.com", "...");
mutation.mutate(credential);

useAuthSignInWithCustomToken

Asynchronously signs in using a custom token.

const mutation = useAuthSignInWithCustomToken(auth);

mutation.mutate("xxxxx");

useAuthSignInWithEmailAndPassword

Asynchronously signs in using a custom token.

const mutation = useAuthSignInWithEmailAndPassword(auth);

mutation.mutate({
  email: "foo@bar.com",
  password: "...",
});

useAuthSignInWithEmailLink

Asynchronously signs in using an email and sign-in email link.

const mutation = useAuthSignInWithEmailLink(auth);

mutation.mutate({
  email: "foo@bar.com",
  emailLink: "https://...", // optional
});

useAuthSignInWithPhoneNumber

Asynchronously signs in using a phone number.

const mutation = useAuthSignInWithPhoneNumber(auth);

mutation.mutate({
  phoneNumber: '+44123456789'
  appVerifier: new RecaptchaVerifier('recaptcha'),
});

useAuthSignInWithPopup

Authenticates a Firebase client using a popup-based OAuth authentication flow.

const mutation = useAuthSignInWithPopup(auth);

mutation.mutate({
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthSignInWithRedirect

Authenticates a Firebase client using a full-page redirect flow.

const mutation = useAuthSignInWithRedirect(auth);

mutation.mutate({
  // Any provider supported...
  provider: new GithubAuthProvider(),
});

useAuthSignOut

Signs out the current user.

const mutation = useAuthSignOut(auth);

mutation.mutate();

useAuthUnlink

Unlinks a provider from a user account.

const mutation = useAuthUnlink();

mutation.mutate({
  user: auth.currentUser,
  providerId: "google.com",
});

useAuthUpdateCurrentUser

Asynchronously sets the provided user as Auth.currentUser on the Auth instance.

const mutation = useAuthUpdateCurrentUser(auth);

mutation.mutate(user); // Some `User` instance
mutation.mutate(null); // Removes the user

useAuthUpdateEmail

Updates the user's email address.

const mutation = useAuthUpdateEmail();

mutation.mutate({
  user: auth.currentUser,
  newEmail: "bar@foo.com",
});

useAuthUpdatePassword

Updates the user's password.

const mutation = useAuthUpdatePassword();

mutation.mutate({
  user: auth.currentUser,
  newPassword: "...",
});

useAuthUpdatePhoneNumber

Updates the user's phone number.

const mutation = useAuthUpdatePhoneNumber();

mutation.mutate({
  user: auth.currentUser,
  // PhoneAuthCredential returned from phone auth flow
  credential,
});

useAuthUpdateProfile

Updates a user's profile data.

const mutation = useAuthUpdateProfile();

mutation.mutate({
  user: auth.currentUser,
  displayName: "...", // optional
  photoURL: "https://...", // optional
});

useAuthVerifyBeforeUpdateEmail

Sends a verification email to a new email address.

const mutation = useAuthVerifyBeforeUpdateEmail();

mutation.mutate({
  user: auth.currentUser,
  newEmail: "bar@foo.com",
  actionCodeSettings: {}, // optional
});

useAuthVerifyPasswordResetCode

Checks a password reset code sent to the user by email or other out-of-band mechanism.

const mutation = useAuthVerifyPasswordResetCode(auth);

mutation.mutate("oobCode");
Edit this page on GitHub
ID Token
Getting Started