@xhub-ui/google-login-lite

Lightweight Google ID Login hook for React. Returns an ID Token (JWT) via the google.accounts.id API — no OAuth2 flows, no button components, just a login() function you wire to your own UI.

Requirements

• React ≥ 16.8
• A Google Cloud OAuth 2.0 Client ID

Installation

npm install @xhub-ui/google-login-lite
# or
yarn add @xhub-ui/google-login-lite

Quick Start

import {
  GoogleOAuthProvider,
  useGoogleIdLogin,
} from "@xhub-ui/google-login-lite";

function LoginButton() {
  const login = useGoogleIdLogin({
    onSuccess: (credentialResponse) => {
      // credentialResponse.credential is the ID Token JWT
      console.log("ID Token:", credentialResponse.credential);
    },
    onError: () => {
      console.error("Login failed");
    },
  });

  return <button onClick={login}>Sign in with Google</button>;
}

export default function App() {
  return (
    <GoogleOAuthProvider clientId="YOUR_CLIENT_ID">
      <LoginButton />
    </GoogleOAuthProvider>
  );
}

API

<GoogleOAuthProvider>

Wrap your app (or the subtree that needs Google login) with this provider. It loads the GSI script and makes clientId available to all hooks below it.

<GoogleOAuthProvider
  clientId="YOUR_CLIENT_ID"
  locale="en"
  onScriptLoadSuccess={() => console.log("GSI ready")}
  onScriptLoadError={() => console.error("GSI failed to load")}
>
  {children}
</GoogleOAuthProvider>

| Prop | Type | Required | Description | | --------------------- | ------------ | -------- | ---------------------------------------------------------- | | clientId | string | ✅ | Your Google OAuth 2.0 client ID | | nonce | string | — | Nonce applied to the GSI <script> tag | | locale | string | — | ISO-639 language code for the GSI UI (e.g. "en", "vi") | | onScriptLoadSuccess | () => void | — | Called when the GSI script loads successfully | | onScriptLoadError | () => void | — | Called when the GSI script fails to load | | children | ReactNode | ✅ | Your component tree |

useGoogleIdLogin(options)

Returns a login() function. Call it on a button click (or any user gesture) to trigger the Google One Tap / Sign In With Google prompt.

const login = useGoogleIdLogin({
  onSuccess, // required
  onError,
  hosted_domain,
  login_hint,
  nonce,
  auto_select,
  cancel_on_tap_outside,
  use_fedcm_for_prompt,
  use_fedcm_for_button,
  promptMomentNotification,
});

Options

| Option | Type | Default | Description | | -------------------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | onSuccess | (res: CredentialResponse) => void | — | Required. Called with the credential response on successful login | | onError | () => void | — | Called when login fails or no credential is returned | | promptMomentNotification | MomentListener | — | Callback for prompt moment notifications | | cancel_on_tap_outside | boolean | — | Cancel the prompt when the user clicks outside | | hosted_domain | string | — | Restrict sign-in to a specific G Suite domain (e.g. "yourcompany.com") | | use_fedcm_for_prompt | boolean | false | Use FedCM for the One Tap prompt | | use_fedcm_for_button | boolean | false | Use FedCM for the Sign In With Google button flow | | auto_select | boolean | — | Automatically select the account if only one session exists | | login_hint | string | — | Pre-fill the account selector with a specific email address | | nonce | string | — | Random string included in the ID token for replay protection |

CredentialResponse

The object passed to onSuccess:

| Field | Type | Description | | ------------ | -------- | ----------------------------------------------------------------- | | credential | string | The ID Token JWT — decode this on your backend to verify the user | | select_by | string | How the credential was selected ("user_1tap", "btn", etc.) | | clientId | string | The client ID that issued the credential |

useGoogleOAuth()

Low-level context hook. Use this if you need direct access to clientId or the script load state.

const { clientId, scriptLoadedSuccessfully } = useGoogleOAuth();

Must be used inside <GoogleOAuthProvider> — throws otherwise.

Exported Types

import type {
  CredentialResponse,
  GoogleCredentialResponse,
  IdConfiguration,
  MomentListener,
  PromptMomentNotification,
  UseGoogleIdLoginOptions,
} from "@xhub-ui/google-login-lite";

Examples

Restrict to a G Suite domain

const login = useGoogleIdLogin({
  hosted_domain: "yourcompany.com",
  onSuccess: (res) => console.log(res.credential),
});

Pre-fill a known email

const login = useGoogleIdLogin({
  login_hint: "[email protected]",
  onSuccess: (res) => console.log(res.credential),
});

Handle prompt moment notifications

const login = useGoogleIdLogin({
  onSuccess: (res) => console.log(res.credential),
  promptMomentNotification: (notification) => {
    if (notification.isNotDisplayed()) {
      console.warn("Prompt not shown:", notification.getNotDisplayedReason());
    }
    if (notification.isSkippedMoment()) {
      console.warn("Prompt skipped:", notification.getSkippedReason());
    }
  },
});

Verify the ID Token on your backend (Node.js example)

import { OAuth2Client } from "google-auth-library";

const client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID);

async function verify(idToken: string) {
  const ticket = await client.verifyIdToken({
    idToken,
    audience: process.env.GOOGLE_CLIENT_ID,
  });
  return ticket.getPayload(); // { sub, email, name, picture, ... }
}

Migrating from @react-oauth/google

| @react-oauth/google | @xhub-ui/google-login-lite | | --------------------------------------- | ---------------------------------------------------- | | useGoogleLogin({ flow: 'implicit' }) | ❌ Not supported (OAuth2 flows removed) | | useGoogleLogin({ flow: 'auth-code' }) | ❌ Not supported | | useGoogleOneTapLogin | useGoogleIdLogin (manual trigger, not auto-prompt) | | GoogleLogin button component | ❌ Removed — bring your own button | | googleLogout | ❌ Removed | | hasGrantedAllScopesGoogle | ❌ Removed | | GoogleOAuthProvider | ✅ Same API | | CredentialResponse | ✅ Same type |

If you only need the ID Token (for "Sign in with Google" flows), the migration is a one-line hook swap.

License

MIT