React OAuth (Google)

@react-oauth/google is a thin, typed React wrapper around Google’s newer Identity Services (GSI) JavaScript SDK, giving React applications Sign In With Google buttons, One Tap sign-up, and full OAuth2 implicit/authorization-code flows without hand-rolling script loading or callback plumbing.

It injects and tracks the GSI script for you via a single GoogleOAuthProvider context, then exposes that state through a small, consistent surface: a drop-in GoogleLogin button component for the declarative case, and useGoogleLogin / useGoogleOneTapLogin hooks for fully custom UI. Helper utilities like hasGrantedAllScopesGoogle remove the need to hand-parse OAuth scope strings from token responses.

With zero runtime dependencies beyond a React peer dependency, extensive TypeScript types (including a discriminated union on useGoogleLogin’s flow option for correct return types per flow), and roughly 1.3M weekly downloads, it has become the de facto standard for adding Google authentication to React apps.

What You Get

• GoogleOAuthProvider context that loads and tracks the Google Identity Services script once for the whole app
• GoogleLogin drop-in button component with One Tap, auto sign-in, and full styling/locale props
• useGoogleLogin hook supporting both implicit and authorization-code OAuth2 flows with correctly-typed responses per flow
• useGoogleOneTapLogin hook for headless One Tap prompts outside the button component
• googleLogout helper to clear One Tap auto-select state on sign-out
• hasGrantedAllScopesGoogle / hasGrantedAnyScopeGoogle helpers for checking granted OAuth scopes without manual string parsing

Common Use Cases

• Adding a ‘Sign in with Google’ button to a React SPA without managing the GSI <script> tag by hand
• One-tap, passwordless sign-up that re-authenticates returning users automatically across sessions
• Custom-styled login buttons using useGoogleLogin while keeping Google’s token/callback semantics
• Authorization-code flow where a backend exchanges the returned code for access and refresh tokens
• Requesting and verifying incremental OAuth scopes (e.g. Calendar, Drive) beyond basic sign-in

Under The Hood

Architecture The package is a thin wrapper over Google’s Identity Services (GSI) JS SDK. useLoadGsiScript dynamically injects a <script> tag pointing at Google’s hosted GSI client and tracks its load state; GoogleOAuthProvider wraps the app in a React Context that carries that load state alongside clientId, exposed via useGoogleOAuth. Every consumer surface — the GoogleLogin component, useGoogleLogin, and useGoogleOneTapLogin — reads that shared context and then calls directly into the global window.google.accounts.oauth2/accounts.id objects the loaded script installs, wrapping user callbacks in refs to avoid stale closures inside the initialization effect. The structure is flat and modular rather than layered: one context provider plus a handful of independent leaf hooks/components, all coupled to the same shared script-loading abstraction.

Tech Stack Written in TypeScript (over 90% of the codebase) and built with Rollup into CommonJS, ESM, and declaration-file outputs. React (>=16.8) is a peer dependency only — the package ships with zero runtime dependencies of its own. The repo is a Yarn 4 + Turborepo monorepo, versioned and published via Changesets, with a GitHub Actions workflow (release.yml) that builds and publishes to npm on pushes to master.

Code Quality No test files exist anywhere in the package (no *.test.*/*.spec.* files, no Jest/Vitest config), and the release CI workflow only builds and publishes — it does not run a test step. Error handling favors callback props (onError, onNonOAuthError) mirroring the underlying GSI callback API, with one thrown Error for the misuse case of calling useGoogleOAuth outside its provider. Naming is consistent and descriptive, and typing is thorough: exported response types and a discriminated flow-keyed union on useGoogleLogin’s options give strong compile-time guarantees. Prettier and Husky/lint-staged enforce formatting repo-wide, but no ESLint config was found scoped to this package.

API Design The public API is deliberately small: wrap the app once in GoogleOAuthProvider, then use either the declarative GoogleLogin button or the imperative useGoogleLogin/useGoogleOneTapLogin hooks for custom UI — no manual script-tag or load-state management required. Overloaded function signatures on useGoogleLogin, keyed off the flow option, return the correctly-typed callback for implicit vs. authorization-code flow without a generic parameter. Boilerplate to get started is minimal, though most props map closely onto Google’s own GSI option names rather than abstracting them, so real-world usage (auth-code exchange, FedCM flags, One Tap edge cases) still benefits from reading Google’s Identity Services docs alongside this package’s README.