feat(ui,react): Introduce OAuthConsent component

.changeset/public-oauth-consent-component.md

@@ -0,0 +1,20 @@
+---
+'@clerk/nextjs': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Introduce `<OAuthConsent />` component for rendering a zero-config OAuth consent screen on an OAuth authorize redirect page.
+
+Usage example:
+
+```tsx
+import { OAuthConsent } from '@clerk/nextjs';
+
+export default function OAuthConsentPage() {
+  return <OAuthConsent />;
+}
+```
+
+The component reads `client_id`, `scope`, and `redirect_uri` from the current URL by default and submits the consent decision internally, so no boilerplate is required for the common OAuth redirect flow. Customization options include `oauthClientId`, `scope`, `appearance`, and `fallback`.

packages/nextjs/src/client-boundary/uiComponents.tsx

@@ -15,6 +15,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationSwitcher,
   PricingTable,

packages/nextjs/src/index.ts

@@ -25,6 +25,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,

packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -26,6 +26,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "CreateOrganization",
   "GoogleOneTap",
   "HandleSSOCallback",
+  "OAuthConsent",
   "OrganizationList",
   "OrganizationProfile",
   "OrganizationSwitcher",

packages/react/src/components/index.ts

@@ -2,6 +2,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,

packages/react/src/components/uiComponents.tsx

@@ -2,6 +2,7 @@ import type {
   APIKeysProps,
   CreateOrganizationProps,
   GoogleOneTapProps,
+  OAuthConsentProps,
   OrganizationListProps,
   OrganizationProfileProps,
   OrganizationSwitcherProps,
@@ -643,6 +644,37 @@ export const APIKeys = withClerk(
   { component: 'ApiKeys', renderWhileLoading: true },
 );
 
+/**
+ * @internal
+ */
+export const OAuthConsent = withClerk(
+  ({ clerk, component, fallback, ...props }: WithClerkProp<OAuthConsentProps & FallbackProp>) => {
+    const mountingStatus = useWaitForComponentMount(component);
+    const shouldShowFallback = mountingStatus === 'rendering' || !clerk.loaded;
+
+    const rendererRootProps = {
+      ...(shouldShowFallback && fallback && { style: { display: 'none' } }),
+    };
+
+    return (
+      <>
+        {shouldShowFallback && fallback}
+        {clerk.loaded && (
+          <ClerkHostRenderer
+            component={component}
+            mount={clerk.__internal_mountOAuthConsent}
+            unmount={clerk.__internal_unmountOAuthConsent}
+            updateProps={(clerk as any).__internal_updateProps}
+            props={props}
+            rootProps={rendererRootProps}
+          />
+        )}
+      </>
+    );
+  },
+  { component: 'OAuthConsent', renderWhileLoading: true },
+);
+
 export const UserAvatar = withClerk(
   ({ clerk, component, fallback, ...props }: WithClerkProp<UserAvatarProps & FallbackProp>) => {
     const mountingStatus = useWaitForComponentMount(component);

packages/shared/src/react/hooks/__tests__/useOAuthConsent.spec.tsx

@@ -50,7 +50,6 @@ describe('useOAuthConsent', () => {
     mockClerk.oauthApplication = {
       getConsentInfo: getConsentInfoSpy,
     };
-    window.history.replaceState({}, '', '/');
   });
 
   it('fetches consent metadata when signed in', async () => {
@@ -104,45 +103,4 @@ describe('useOAuthConsent', () => {
     expect(getConsentInfoSpy).not.toHaveBeenCalled();
     expect(result.current.isLoading).toBe(false);
   });
-
-  it('uses client_id and scope from the URL when hook params omit them', async () => {
-    window.history.replaceState({}, '', '/?client_id=from_url&scope=openid%20email');
-
-    const { result } = renderHook(() => useOAuthConsent(), { wrapper });
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(getConsentInfoSpy).toHaveBeenCalledTimes(1);
-    expect(getConsentInfoSpy).toHaveBeenCalledWith({ oauthClientId: 'from_url', scope: 'openid email' });
-    expect(result.current.data).toEqual(consentInfo);
-  });
-
-  it('prefers explicit oauthClientId over URL client_id', async () => {
-    window.history.replaceState({}, '', '/?client_id=from_url');
-
-    const { result } = renderHook(() => useOAuthConsent({ oauthClientId: 'explicit_id' }), { wrapper });
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(getConsentInfoSpy).toHaveBeenCalledWith({ oauthClientId: 'explicit_id' });
-  });
-
-  it('does not fall back to URL client_id when oauthClientId is explicitly empty', () => {
-    window.history.replaceState({}, '', '/?client_id=from_url');
-
-    const { result } = renderHook(() => useOAuthConsent({ oauthClientId: '' }), { wrapper });
-
-    expect(getConsentInfoSpy).not.toHaveBeenCalled();
-    expect(result.current.isLoading).toBe(false);
-  });
-
-  it('prefers explicit scope over URL scope', async () => {
-    window.history.replaceState({}, '', '/?client_id=cid&scope=from_url');
-
-    const { result } = renderHook(() => useOAuthConsent({ scope: 'explicit_scope' }), { wrapper });
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(getConsentInfoSpy).toHaveBeenCalledWith({ oauthClientId: 'cid', scope: 'explicit_scope' });
-  });
 });

packages/shared/src/react/hooks/useOAuthConsent.shared.ts

@@ -4,24 +4,6 @@ import type { GetOAuthConsentInfoParams } from '../../types';
 import { STABLE_KEYS } from '../stable-keys';
 import { createCacheKeys } from './createCacheKeys';
 
-/**
- * Parses OAuth authorize-style query data from a search string (typically `window.location.search`).
- *
- * @internal
- */
-export function readOAuthConsentFromSearch(search: string): {
-  oauthClientId: string;
-  scope?: string;
-} {
-  const sp = new URLSearchParams(search);
-  const oauthClientId = sp.get('client_id') ?? '';
-  const scopeValue = sp.get('scope');
-  if (scopeValue === null) {
-    return { oauthClientId };
-  }
-  return { oauthClientId, scope: scopeValue };
-}
-
 export function useOAuthConsentCacheKeys(params: { userId: string | null; oauthClientId: string; scope?: string }) {
   const { userId, oauthClientId, scope } = params;
   return useMemo(() => {

packages/shared/src/react/hooks/useOAuthConsent.tsx

@@ -1,14 +1,12 @@
 'use client';
 
-import { useMemo } from 'react';
-
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type { LoadedClerk } from '../../types/clerk';
 import { defineKeepPreviousDataFn } from '../clerk-rq/keep-previous-data';
 import { useClerkQuery } from '../clerk-rq/useQuery';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import { useUserBase } from './base/useUserBase';
-import { readOAuthConsentFromSearch, useOAuthConsentCacheKeys } from './useOAuthConsent.shared';
+import { useOAuthConsentCacheKeys } from './useOAuthConsent.shared';
 import type { UseOAuthConsentParams, UseOAuthConsentReturn } from './useOAuthConsent.types';
 
 const HOOK_NAME = 'useOAuthConsent';
@@ -18,26 +16,13 @@ const HOOK_NAME = 'useOAuthConsent';
  * (`GET /me/oauth/consent/{oauthClientId}`). Ensure the user is authenticated before relying on this hook
  * (for example, redirect to sign-in on your custom consent route).
  *
- * `oauthClientId` and `scope` are optional. On the client, values default from a single snapshot of
- * `window.location.search` (`client_id` and `scope`). Pass them explicitly to override.
+ * The hook is a pure data fetcher: it takes an explicit `oauthClientId` and optional `scope` and
+ * issues the fetch when both the user is signed in and `oauthClientId` is non-empty. The query is
+ * disabled when `oauthClientId` is empty or omitted.
  *
  * @internal
  *
  * @example
- * ### From the URL (`?client_id=...&scope=...`)
- *
- * ```tsx
- * import { useOAuthConsent } from '@clerk/react/internal'
- *
- * export default function OAuthConsentPage() {
- *   const { data, isLoading, error } = useOAuthConsent()
- *   // ...
- * }
- * ```
- *
- * @example
- * ### Explicit values (override URL)
- *
  * ```tsx
  * import { useOAuthConsent } from '@clerk/react/internal'
  *
@@ -50,19 +35,11 @@ const HOOK_NAME = 'useOAuthConsent';
 export function useOAuthConsent(params: UseOAuthConsentParams = {}): UseOAuthConsentReturn {
   useAssertWrappedByClerkProvider(HOOK_NAME);
 
-  const { oauthClientId: oauthClientIdParam, scope: scopeParam, keepPreviousData = true, enabled = true } = params;
+  const { oauthClientId: oauthClientIdParam, scope, keepPreviousData = true, enabled = true } = params;
   const clerk = useClerkInstanceContext();
   const user = useUserBase();
 
-  const fromUrl = useMemo(() => {
-    if (typeof window === 'undefined' || !window.location) {
-      return { oauthClientId: '' };
-    }
-    return readOAuthConsentFromSearch(window.location.search);
-  }, []);
-
-  const oauthClientId = (oauthClientIdParam !== undefined ? oauthClientIdParam : fromUrl.oauthClientId).trim();
-  const scope = scopeParam !== undefined ? scopeParam : fromUrl.scope;
+  const oauthClientId = (oauthClientIdParam ?? '').trim();
 
   clerk.telemetry?.record(eventMethodCalled(HOOK_NAME));
 

packages/shared/src/react/hooks/useOAuthConsent.types.ts

@@ -4,9 +4,8 @@ import type { GetOAuthConsentInfoParams, OAuthConsentInfo } from '../../types';
 /**
  * Options for {@link useOAuthConsent}.
  *
- * `oauthClientId` and `scope` are optional. On the browser, the hook reads a one-time snapshot of
- * `window.location.search` and uses `client_id` and `scope` query keys when you omit them here.
- * Any value you pass explicitly overrides the snapshot for that field only.
+ * Pass `oauthClientId` and `scope` explicitly. The hook does not read from `window.location` or
+ * any other ambient source. The hook is disabled when `oauthClientId` is empty or omitted.
  *
  * @internal
  * @interface

packages/shared/src/types/clerk.ts

@@ -2270,7 +2270,7 @@ export type __internal_OAuthConsentProps = {
   /**
    * Name of the OAuth application.
    */
-  oAuthApplicationName: string;
+  oAuthApplicationName?: string;
   /**
    * Logo URL of the OAuth application.
    */
@@ -2282,23 +2282,43 @@ export type __internal_OAuthConsentProps = {
   /**
    * Scopes requested by the OAuth application.
    */
-  scopes: {
+  scopes?: {
     scope: string;
     description: string | null;
     requires_consent: boolean;
   }[];
   /**
    * Full URL or path to navigate to after the user allows access.
    */
-  redirectUrl: string;
+  redirectUrl?: string;
   /**
    * Called when user allows access.
    */
-  onAllow: () => void;
+  onAllow?: () => void;
   /**
    * Called when user denies access.
    */
-  onDeny: () => void;
+  onDeny?: () => void;
+};
+
+/**
+ * Props for the public `<OAuthConsent />` React component.
+ */
+export type OAuthConsentProps = {
+  /**
+   * Override the OAuth client ID. Defaults to the `client_id` query parameter
+   * from the current URL.
+   */
+  oauthClientId?: string;
+  /**
+   * Override the OAuth scope. Defaults to the `scope` query parameter from
+   * the current URL.
+   */
+  scope?: string;
+  /**
+   * Customize the appearance of the component.
+   */
+  appearance?: ClerkAppearanceTheme;
 };
 
 export interface HandleEmailLinkVerificationParams {

packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -32,6 +32,7 @@ exports[`root public exports > should not change unexpectedly 1`] = `
   "CreateOrganization",
   "GoogleOneTap",
   "HandleSSOCallback",
+  "OAuthConsent",
   "OrganizationList",
   "OrganizationProfile",
   "OrganizationSwitcher",