useSignInWithCredentialMutation.mdx

title
useSignInWithCredentialMutation

The useSignInWithCredentialMutation hook is designed to handle user sign-ins using Firebase Authentication credentials, such as Google sign-in credentials. It integrates Firebase's signInWithCredential method with TanStack Query’s mutation lifecycle for easy state management and error handling.

Features

• Firebase Authentication Integration: Simplifies signing in with any valid Firebase AuthCredential (e.g., Google, Facebook, etc.).
• Built-in State Management: Tracks the mutation lifecycle (idle, loading, success, error).
• Customizable Callbacks: Supports onSuccess, onError, and other TanStack Query mutation options.
• Type-Safe Handling: Ensures type safety with TanStack Query and Firebase types.

Installation

Ensure you have the necessary Firebase, TanStack Query and TanStack Query Firebase packages installed:

npm install firebase @tanstack/react-query @tanstack-query-firebase/react

Usage

import { useSignInWithCredentialMutation } from "@tanstack-query-firebase/react/auth";
import { GoogleAuthProvider } from "firebase/auth";

const authCredential = GoogleAuthProvider.credential("your-id-token");

function SignInComponent() {
  const { mutate, isPending, isSuccess, isError, error, data } = useSignInWithCredentialMutation(auth, authCredential);

  const handleSignIn = () => {
    mutate(); // Trigger the sign-in mutation
  };

  return (
    <div>
      {isPending && <p>Signing in...</p>}
      {isSuccess && <p>Signed in as {data?.user.email}</p>}
      {isError && <p>Error: {error?.message}</p>}

      <button onClick={handleSignIn} disabled={isPending}>
        Sign In
      </button>
    </div>
  );
}

API Reference

useSignInWithCredentialMutation(auth, credential, options?)

Parameters

• auth: The Firebase Auth instance used to manage authentication.
• credential: An instance of AuthCredential (e.g., GoogleAuthProvider.credential).
• options (optional):
  An object for customizing the mutation behavior. Accepts all options supported by TanStack Query's useMutation, such as:
  • onSuccess: Callback fired when the mutation succeeds.
  • onError: Callback fired when the mutation fails.
  • onSettled: Callback fired after the mutation finishes, regardless of success or failure.

For a full list of supported options, see the TanStack Query useMutation documentation

Returns

The hook returns the following properties, provided by TanStack Query's useMutation:

• mutate: Function to trigger the sign-in mutation with the provided credential.

mutate(): void;

• isPending: Boolean indicating if the mutation is in progress (alias for isLoading).

• isSuccess: Boolean indicating if the mutation has successfully completed.

• isError: Boolean indicating if the mutation has failed.

• error: The error object, if the mutation failed.

• data: The result of the sign-in, typically containing the authenticated user object.

For a complete list of returned properties, see the official TanStack Query useMutation documentation.