feat(shared,ui,react,nextjs): add public <OAuthConsent /> component

wobsoriano · wobsoriano · commit 12b1ebba4c0e · 2026-04-11T03:48:44.000-07:00
Introduce a zero-config &lt;OAuthConsent /&gt; React component exported from
@clerk/react and @clerk/nextjs that renders the OAuth consent screen for a
signed-in user. The component reads client_id, scope, and redirect_uri from
the URL by default and submits the consent decision via a native form POST
to /v1/internal/oauth-consent.

The accounts portal continues to work unchanged via the existing
clerk.__internal_mountOAuthConsent path; the underlying UI component is a
hybrid that uses context values when provided (accounts portal path) and
falls back to the useOAuthConsent hook + URL parsing otherwise (public path).

Highlights:
- New public OAuthConsentProps type in @clerk/shared
- OAuthConsentCtx refactored to lowercase oauth* casing with translation
  layer in ComponentContextProvider for accounts portal backward compat
- Hybrid _OAuthConsent component with native form wrapping and submit
  buttons (proper a11y semantics)
- URL parsing moved out of useOAuthConsent hook into the component for
  cleaner separation of concerns and SSR safety
- New &lt;OAuthConsent /&gt; wrapper in @clerk/react re-exported from @clerk/nextjs
- 7 unit tests covering public and accounts portal paths
- Export snapshot updates for react-router and tanstack-react-start
diff --git a/.changeset/public-oauth-consent-component.md b/.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`.
diff --git a/packages/nextjs/src/client-boundary/uiComponents.tsx b/packages/nextjs/src/client-boundary/uiComponents.tsx
@@ -15,6 +15,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationSwitcher,
   PricingTable,
diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts
@@ -25,6 +25,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,
diff --git a/packages/react-router/src/__tests__/__snapshots__/exports.test.ts.snap b/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",
diff --git a/packages/react/src/components/index.ts b/packages/react/src/components/index.ts
@@ -2,6 +2,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,
diff --git a/packages/react/src/components/uiComponents.tsx b/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);
diff --git a/packages/shared/src/react/hooks/__tests__/useOAuthConsent.shared.spec.ts b/packages/shared/src/react/hooks/__tests__/useOAuthConsent.shared.spec.ts
diff --git a/packages/shared/src/react/hooks/__tests__/useOAuthConsent.spec.tsx b/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' });
-  });
 });
diff --git a/packages/shared/src/react/hooks/useOAuthConsent.shared.ts b/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(() => {
diff --git a/packages/shared/src/react/hooks/useOAuthConsent.tsx b/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));
 
diff --git a/packages/shared/src/react/hooks/useOAuthConsent.types.ts b/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
diff --git a/packages/shared/src/types/clerk.ts b/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 {
diff --git a/packages/tanstack-react-start/src/__tests__/__snapshots__/exports.test.ts.snap b/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",
diff --git a/packages/ui/src/components/OAuthConsent/OAuthConsent.tsx b/packages/ui/src/components/OAuthConsent/OAuthConsent.tsx
diff --git a/packages/ui/src/components/OAuthConsent/__tests__/OAuthConsent.spec.tsx b/packages/ui/src/components/OAuthConsent/__tests__/OAuthConsent.spec.tsx
diff --git a/packages/ui/src/contexts/ClerkUIComponentsContext.tsx b/packages/ui/src/contexts/ClerkUIComponentsContext.tsx
diff --git a/packages/ui/src/types.ts b/packages/ui/src/types.ts
