useGitHubLogin

React hook for GitHub OAuth authentication using the Authorization Code flow with a popup window.

Overview

useGitHubLogin is a custom React hook that handles the full GitHub OAuth 2.0 Authorization Code flow. It opens a popup window, polls for the authorization code, verifies the CSRF state, and calls your callbacks when the flow completes or fails.

useGitHubLogin(options: UseGitHubLoginOptions): UseGitHubLoginReturn

The hook uses a popup window with polling — it never redirects the main page. The authorization code returned by onSuccess must be exchanged for an access token on your backend; never do this client-side.

Usage

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

function LoginButton() {
  const { initiateGitHubLogin, isLoading } = useGitHubLogin({
    clientId: 'your-github-client-id',
    redirectUri: 'http://localhost:3000/callback',
    onSuccess: (response) => {
      // Send response.code to your backend to exchange for an access token
      console.log('Authorization code:', response.code);
    },
    onError: (error) => {
      console.error('Authentication failed:', error);
    },
  });

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

Options

clientId · string · required

Your GitHub OAuth App Client ID. You can find this in your GitHub Developer Settings under your OAuth App.

onSuccess · (response: OAuthResponse) => void · required

Callback called when authentication succeeds. Receives an OAuthResponse object containing the authorization code and optional state.

onError · (error: Error) => void · required

Callback called when authentication fails for any reason. The error argument may be an OAuthError instance — use OAuthError.isOAuthError(error) to narrow the type and inspect the code property.

redirectUri · string · default: "''"

The redirect URI registered in your GitHub OAuth App settings. Must match exactly what you configured in GitHub.

scope · string · default: "'user:email'"

A space- or comma-separated list of OAuth scopes to request. See the common scopes section below.

popupOptions · PopupWindowOptions

Options for configuring the popup window size and position. See PopupWindowOptions below.

Show properties

height · number

Height of the popup window in pixels. Defaults to 700.

width · number

Width of the popup window in pixels. Defaults to 500.

left · number

Left position of the popup window in pixels. Defaults to center of screen.

top · number

Top position of the popup window in pixels. Defaults to center of screen.

state · string

A custom CSRF state parameter. If you omit this, the hook auto-generates a random string. The state is verified when the OAuth callback returns — a mismatch triggers an OAuthError with code OA003.

allowSignup · boolean · default: "true"

When set to false, passes allow_signup=false to GitHub’s authorize endpoint, preventing new users from creating a GitHub account during the OAuth flow.

onRequest · () => void

Optional callback called immediately when the OAuth flow is initiated, before the popup opens. Useful for analytics or to show a loading indicator before isLoading is set.

Return value

initiateGitHubLogin · () => void

Call this function to start the OAuth flow. It opens the GitHub authorization popup and begins polling for the response. If a flow is already in progress, calling this again is a no-op.

isLoading · boolean

true while the OAuth flow is in progress (from the moment the popup opens until onSuccess or onError is called). Use this to disable your login button and prevent duplicate requests.

Types

UseGitHubLoginOptions

type UseGitHubLoginOptions = {
  clientId: string;
  redirectUri?: string;
  scope?: string;
  popupOptions?: PopupWindowOptions;
  state?: string;
  allowSignup?: boolean;
  onSuccess: (response: OAuthResponse) => void;
  onError: (error: Error) => void;
  onRequest?: () => void;
};

UseGitHubLoginReturn

type UseGitHubLoginReturn = {
  initiateGitHubLogin: () => void;
  isLoading: boolean;
};

OAuthResponse

The object passed to your onSuccess callback.

type OAuthResponse = {
  code: string;
  state?: string;
  error?: string;
  error_description?: string;
};

code · string

The authorization code returned by GitHub. Send this to your backend to exchange for an access token.

state · string

The CSRF state parameter echoed back by GitHub. The hook verifies this against the original state automatically.

error · string

Present when GitHub returns an error in the redirect URL (e.g., access_denied).

error_description · string

Human-readable description of the error returned by GitHub, when present.

PopupWindowOptions

type PopupWindowOptions = {
  height?: number;
  width?: number;
  left?: number;
  top?: number;
};

Common scopes

Scope	Description
user:email	Read the user’s email addresses. This is the default scope.
repo	Full control of public and private repositories.
read:org	Read organization and team membership.
gist	Create and update gists.
notifications	Access notifications.

Request only the scopes your application needs. GitHub displays all requested scopes to the user during authorization.

CSRF protection

The hook automatically generates a random state parameter for each OAuth flow and verifies it when GitHub redirects back. If the state does not match, onError is called with an OAuthError with code OA003.

You can provide your own state value for additional verification in onSuccess:

const { initiateGitHubLogin } = useGitHubLogin({
  clientId: 'your-client-id',
  state: 'my-custom-state',
  onSuccess: (response) => {
    if (response.state !== 'my-custom-state') {
      // This check is already done by the hook, but you can add your own logic here
      return;
    }
    // Proceed with the authorization code
    sendCodeToBackend(response.code);
  },
  onError: (error) => console.error(error),
});