Introduction

A zero-dependency React hook for GitHub OAuth authentication with full TypeScript support and built-in CSRF protection.

@react-oauth/github is a modern, production-ready 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 hands you the code — all with no runtime dependencies beyond React itself.

This package works with GitHub OAuth Apps, not GitHub Apps. Make sure you create an OAuth App in your GitHub Developer Settings.

Installation

npm

npm install @react-oauth/github

Requirements: React 16.8 or later and react-dom of the same version.

Key features

TypeScript support

Every hook, option, return value, and error type is fully typed. Exported interfaces let you type your own callbacks without guessing.

Zero dependencies

No runtime dependencies beyond React peer deps. The package adds nothing to your bundle except the hook itself.

CSRF protection

A cryptographically random state parameter is auto-generated on every login attempt and verified when the popup returns.

Custom UI

useGitHubLogin returns a function and a loading boolean. You render whatever button or trigger you want.

Structured error handling

Four named error codes (OA001–OA004) cover every failure mode: popup closed, popup blocked, state mismatch, and missing code.

Popup flow

Authentication happens in a popup so users never leave your page. The popup size and position are configurable.

How the OAuth flow works

@react-oauth/github implements the OAuth 2.0 Authorization Code Flow using a popup window. Here is what happens when a user clicks your login button:

1. Your app opens a popup pointed at https://github.com/login/oauth/authorize with your client_id, requested scope, redirect_uri, and a generated state parameter.
2. GitHub shows the user a login and authorization page.
3. After the user authorizes, GitHub redirects the popup to your redirect_uri with a short-lived code and the original state appended as query parameters.
4. The hook polls the popup’s location every 500 ms. Once the popup lands on your domain, it extracts the code and state from the URL.
5. The state is compared against the value that was sent in step 1. A mismatch triggers an OA003 error.
6. Your onSuccess callback receives the code. You send it to your backend, which exchanges it for an access token using your Client Secret — which never touches the browser.

The authorization code returned by onSuccess is not an access token. You must exchange it server-side. Never expose your Client Secret in frontend code.

Quick example

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 ? 'Loading...' : 'Sign in with GitHub'}
    </button>
  );
}

Next steps

Quickstart

Get GitHub OAuth working in your app with a complete step-by-step guide.

API reference

Full reference for useGitHubLogin options, return values, and types.