Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MomenSherif/react-oauth/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

OAuthError is not a class but an object with factory functions and a type guard. All OAuth-specific errors produced by the hook are plain Error instances with a name of "OAuthError" and a code property set to one of the OAuthErrorCode constants. Use OAuthError.isOAuthError(error) to narrow an unknown error to the OAuthError type, then inspect error.code to determine what went wrong.

​
Import

import { OAuthError, OAuthErrorCode } from '@react-oauth/github';

​
OAuthError

OAuthError is an object containing factory functions and a type guard. There is no new OAuthError() constructor.

​
Type definition

type OAuthError = Error & {
  code: OAuthErrorCode;
};
Every OAuthError instance is a standard Error with:
  • name set to "OAuthError"
  • message set to "<code> <description>" (e.g., "OA001 The Popup Closed")
  • code set to one of the OAuthErrorCode values

​
OAuthError.isOAuthError

OAuthError.isOAuthError(error: unknown): error is OAuthError
A type guard that returns true when error is an Error instance with a valid code property matching one of the known OAuthErrorCode values. Use this before accessing error.code to avoid runtime errors when handling the onError callback. 
onError: (error) => {
  if (OAuthError.isOAuthError(error)) {
    // error.code is now typed as OAuthErrorCode
    console.log(error.code);
  }
}

​
OAuthErrorCode

OAuthErrorCode is a const object that maps error names to their string codes. The type OAuthErrorCode is the union of all its values.

​
Type definition

const OAuthErrorCode = {
  POPUP_CLOSED:   'OA001',
  POPUP_BLOCKED:  'OA002',
  STATE_MISMATCH: 'OA003',
  MISSING_CODE:   'OA004',
} as const;

type OAuthErrorCode = typeof OAuthErrorCode[keyof typeof OAuthErrorCode];

​
Error codes

ConstantCodeDescription
OAuthErrorCode.POPUP_CLOSEDOA001The user closed the popup window before completing authentication.
OAuthErrorCode.POPUP_BLOCKEDOA002The browser blocked the popup window. The user needs to allow popups for your site.
OAuthErrorCode.STATE_MISMATCHOA003The state parameter returned by GitHub does not match the original value. Possible CSRF attack.
OAuthErrorCode.MISSING_CODEOA004The authorization code was not present in GitHub’s redirect response.
A STATE_MISMATCH error (OA003) may indicate a CSRF attack. Do not proceed with the OAuth flow if this error occurs.

​
Usage example

import { useGitHubLogin, OAuthError, OAuthErrorCode } from '@react-oauth/github';

function LoginButton() {
  const { initiateGitHubLogin, isLoading } = useGitHubLogin({
    clientId: 'your-client-id',
    onSuccess: (response) => {
      sendCodeToBackend(response.code);
    },
    onError: (error) => {
      if (OAuthError.isOAuthError(error)) {
        switch (error.code) {
          case OAuthErrorCode.POPUP_CLOSED:
            // User dismissed the popup — no action needed
            console.log('User closed the login popup');
            break;

          case OAuthErrorCode.POPUP_BLOCKED:
            // Ask the user to allow popups for this site
            alert('Please allow popups for this site and try again.');
            break;

          case OAuthErrorCode.STATE_MISMATCH:
            // Possible CSRF — treat as a security issue
            console.error('CSRF state mismatch detected');
            break;

          case OAuthErrorCode.MISSING_CODE:
            // GitHub redirected back without a code
            console.error('Authorization code not found in response');
            break;

          default:
            console.error('OAuth error:', error.message);
        }
      } else {
        // Non-OAuth error (e.g., network failure)
        console.error('Unexpected error:', error);
      }
    },
  });

  return (
    <button onClick={initiateGitHubLogin} disabled={isLoading}>
      {isLoading ? 'Authenticating...' : 'Sign in with GitHub'}
    </button>
  );
}

​
Handling popup blocked

OA002 occurs when the browser blocks the popup. This typically happens when initiateGitHubLogin is not called directly from a user gesture (such as a click handler). Calling it inside a setTimeout, Promise, or other async callback after the user gesture may cause browsers to block the popup.
Always call initiateGitHubLogin synchronously inside a click handler to ensure the browser treats it as a user-initiated popup.

Build docs developers (and LLMs) love

Get started for freeTalk to us