feat(clerk-js): Introduce UNSAFE_PortalProvider

.changeset/wicked-friends-exist.md

@@ -0,0 +1,42 @@
+---
+'@clerk/tanstack-react-start': minor
+'@clerk/react-router': minor
+'@clerk/nextjs': minor
+'@clerk/shared': minor
+'@clerk/astro': minor
+'@clerk/react': minor
+'@clerk/expo': minor
+'@clerk/nuxt': minor
+'@clerk/vue': minor
+'@clerk/ui': minor
+---
+
+Introduce `<UNSAFE_PortalProvider>` component which allows you to specify a custom container for Clerk floating UI elements (popovers, modals, tooltips, etc.) that use portals. Only Clerk components within the provider will be affected, components outside the provider will continue to use the default document.body for portals.
+
+This is particularly useful when using Clerk components inside external UI libraries like [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) or [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html), where portaled elements need to render within the dialog's container to remain interact-able.
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import * as Dialog from '@radix-ui/react-dialog';
+import { UNSAFE_PortalProvider, UserButton } from '@clerk/nextjs';
+
+export function UserDialog() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content ref={containerRef}>
+          <UNSAFE_PortalProvider getContainer={() => containerRef.current}>
+            <UserButton />
+          </UNSAFE_PortalProvider>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```

packages/astro/src/react/index.ts

@@ -8,6 +8,7 @@ import { SubscriptionDetailsButton, type SubscriptionDetailsButtonProps } from '
 export * from './uiComponents';
 export * from './controlComponents';
 export * from './hooks';
+export { UNSAFE_PortalProvider } from '@clerk/shared/react';
 export { SignInButton, SignOutButton, SignUpButton };
 export {
   SubscriptionDetailsButton as __experimental_SubscriptionDetailsButton,

packages/expo/src/index.ts

@@ -13,6 +13,7 @@ export { getClerkInstance } from './provider/singleton';
 export * from './provider/ClerkProvider';
 export * from './hooks';
 export * from './components';
+export { UNSAFE_PortalProvider } from '@clerk/react';
 
 // Override Clerk React error thrower to show that errors come from @clerk/expo
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });

packages/nextjs/src/client-boundary/controlComponents.ts

@@ -12,6 +12,7 @@ export {
   RedirectToSignUp,
   RedirectToTasks,
   RedirectToUserProfile,
+  UNSAFE_PortalProvider,
   Show,
 } from '@clerk/react';
 

packages/nextjs/src/index.ts

@@ -8,6 +8,7 @@ export {
   ClerkFailed,
   ClerkLoaded,
   ClerkLoading,
+  UNSAFE_PortalProvider,
   RedirectToCreateOrganization,
   RedirectToOrganizationProfile,
   RedirectToSignIn,

packages/nuxt/src/runtime/components/index.ts

@@ -23,4 +23,5 @@ export {
   SignOutButton,
   SignInWithMetamaskButton,
   PricingTable,
+  UNSAFE_PortalProvider,
 } from '@clerk/vue';

packages/react-router/src/client/index.ts

@@ -1,3 +1,4 @@
 export * from './ReactRouterClerkProvider';
 export type { WithClerkState } from './types';
 export { SignIn, SignUp, OrganizationProfile, UserProfile } from './uiComponents';
+export { UNSAFE_PortalProvider } from '@clerk/react';

packages/react/src/components/withClerk.tsx

@@ -1,3 +1,4 @@
+import { usePortalRoot } from '@clerk/shared/react';
 import type { LoadedClerk, Without } from '@clerk/shared/types';
 import React from 'react';
 
@@ -19,13 +20,15 @@ export const withClerk = <P extends { clerk: LoadedClerk; component?: string }>(
     useAssertWrappedByClerkProvider(displayName || 'withClerk');
 
     const clerk = useIsomorphicClerkContext();
+    const getContainer = usePortalRoot();
 
     if (!clerk.loaded && !options?.renderWhileLoading) {
       return null;
     }
 
     return (
       <Component
+        getContainer={getContainer}
         {...(props as P)}
         component={displayName}
         clerk={clerk}

packages/react/src/contexts/index.ts

@@ -1 +1,2 @@
 export { ClerkProvider } from './ClerkProvider';
+export { UNSAFE_PortalProvider } from '@clerk/shared/react';

packages/shared/src/react/PortalProvider.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import React from 'react';
+
+import { createContextAndHook } from './hooks/createContextAndHook';
+
+type PortalProviderProps = React.PropsWithChildren<{
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer: () => HTMLElement | null;
+}>;
+
+const [PortalContext, , usePortalContextWithoutGuarantee] = createContextAndHook<{
+  getContainer: () => HTMLElement | null;
+}>('PortalProvider');
+
+/**
+ * UNSAFE_PortalProvider allows you to specify a custom container for Clerk floating UI elements
+ * (popovers, modals, tooltips, etc.) that use portals.
+ *
+ * Only components within this provider will be affected. Components outside the provider
+ * will continue to use the default document.body for portals.
+ *
+ * This is particularly useful when using Clerk components inside external UI libraries
+ * like Radix Dialog or React Aria Components, where portaled elements need to render
+ * within the dialog's container to remain interactable.
+ *
+ * @example
+ * ```tsx
+ * function Example() {
+ *   const containerRef = useRef(null);
+ *   return (
+ *     <RadixDialog ref={containerRef}>
+ *       <UNSAFE_PortalProvider getContainer={() => containerRef.current}>
+ *         <UserButton />
+ *       </UNSAFE_PortalProvider>
+ *     </RadixDialog>
+ *   );
+ * }
+ * ```
+ */
+export const UNSAFE_PortalProvider = ({ children, getContainer }: PortalProviderProps) => {
+  const contextValue = React.useMemo(() => ({ value: { getContainer } }), [getContainer]);
+
+  return <PortalContext.Provider value={contextValue}>{children}</PortalContext.Provider>;
+};
+
+/**
+ * Hook to get the current portal root container.
+ * Returns the getContainer function from context if inside a PortalProvider,
+ * otherwise returns a function that returns null (default behavior).
+ */
+export const usePortalRoot = (): (() => HTMLElement | null) => {
+  const contextValue = usePortalContextWithoutGuarantee();
+
+  if (contextValue && 'getContainer' in contextValue && contextValue.getContainer) {
+    return contextValue.getContainer;
+  }
+
+  // Return a function that returns null when not inside a PortalProvider
+  return () => null;
+};

packages/shared/src/react/__tests__/PortalProvider.test.tsx

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+
+import { UNSAFE_PortalProvider, usePortalRoot } from '../PortalProvider';
+
+describe('UNSAFE_PortalProvider', () => {
+  it('provides getContainer to children via context', () => {
+    const container = document.createElement('div');
+    const getContainer = () => container;
+
+    const TestComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='test'>{portalRoot === getContainer ? 'found' : 'not-found'}</div>;
+    };
+
+    render(
+      <UNSAFE_PortalProvider getContainer={getContainer}>
+        <TestComponent />
+      </UNSAFE_PortalProvider>,
+    );
+
+    expect(screen.getByTestId('test').textContent).toBe('found');
+  });
+
+  it('only affects components within the provider', () => {
+    const container = document.createElement('div');
+    const getContainer = () => container;
+
+    const InsideComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='inside'>{portalRoot() === container ? 'container' : 'null'}</div>;
+    };
+
+    const OutsideComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='outside'>{portalRoot() === null ? 'null' : 'container'}</div>;
+    };
+
+    render(
+      <>
+        <OutsideComponent />
+        <UNSAFE_PortalProvider getContainer={getContainer}>
+          <InsideComponent />
+        </UNSAFE_PortalProvider>
+      </>,
+    );
+
+    expect(screen.getByTestId('inside').textContent).toBe('container');
+    expect(screen.getByTestId('outside').textContent).toBe('null');
+  });
+});
+
+describe('usePortalRoot', () => {
+  it('returns getContainer from context when inside PortalProvider', () => {
+    const container = document.createElement('div');
+    const getContainer = () => container;
+
+    const TestComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='test'>{portalRoot() === container ? 'found' : 'not-found'}</div>;
+    };
+
+    render(
+      <UNSAFE_PortalProvider getContainer={getContainer}>
+        <TestComponent />
+      </UNSAFE_PortalProvider>,
+    );
+
+    expect(screen.getByTestId('test').textContent).toBe('found');
+  });
+
+  it('returns a function that returns null when outside PortalProvider', () => {
+    const TestComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='test'>{portalRoot() === null ? 'null' : 'not-null'}</div>;
+    };
+
+    render(<TestComponent />);
+
+    expect(screen.getByTestId('test').textContent).toBe('null');
+  });
+
+  it('supports nested providers with innermost taking precedence', () => {
+    const outerContainer = document.createElement('div');
+    const innerContainer = document.createElement('div');
+
+    const TestComponent = () => {
+      const portalRoot = usePortalRoot();
+      return <div data-testid='test'>{portalRoot() === innerContainer ? 'inner' : 'outer'}</div>;
+    };
+
+    render(
+      <UNSAFE_PortalProvider getContainer={() => outerContainer}>
+        <UNSAFE_PortalProvider getContainer={() => innerContainer}>
+          <TestComponent />
+        </UNSAFE_PortalProvider>
+      </UNSAFE_PortalProvider>,
+    );
+
+    expect(screen.getByTestId('test').textContent).toBe('inner');
+  });
+});

packages/shared/src/react/index.ts

@@ -20,3 +20,5 @@ export {
 } from './contexts';
 
 export * from './billing/payment-element';
+
+export { UNSAFE_PortalProvider, usePortalRoot } from './PortalProvider';

packages/shared/src/types/clerk.ts

@@ -1440,9 +1440,22 @@ export interface TransferableOption {
   transferable?: boolean;
 }
 
-export type SignInModalProps = WithoutRouting<SignInProps>;
+export type SignInModalProps = WithoutRouting<SignInProps> & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 export type __internal_UserVerificationProps = RoutingOptions & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
   /**
    * Non-awaitable callback for when verification is completed successfully
    */
@@ -1584,7 +1597,14 @@ export type SignUpProps = RoutingOptions & {
   SignInForceRedirectUrl &
   AfterSignOutUrl;
 
-export type SignUpModalProps = WithoutRouting<SignUpProps>;
+export type SignUpModalProps = WithoutRouting<SignUpProps> & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 export type UserProfileProps = RoutingOptions & {
   /**
@@ -1626,7 +1646,14 @@ export type UserProfileProps = RoutingOptions & {
   };
 };
 
-export type UserProfileModalProps = WithoutRouting<UserProfileProps>;
+export type UserProfileModalProps = WithoutRouting<UserProfileProps> & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 export type OrganizationProfileProps = RoutingOptions & {
   /**
@@ -1669,7 +1696,14 @@ export type OrganizationProfileProps = RoutingOptions & {
   };
 };
 
-export type OrganizationProfileModalProps = WithoutRouting<OrganizationProfileProps>;
+export type OrganizationProfileModalProps = WithoutRouting<OrganizationProfileProps> & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 export type CreateOrganizationProps = RoutingOptions & {
   /**
@@ -1695,7 +1729,14 @@ export type CreateOrganizationProps = RoutingOptions & {
   appearance?: ClerkAppearanceTheme;
 };
 
-export type CreateOrganizationModalProps = WithoutRouting<CreateOrganizationProps>;
+export type CreateOrganizationModalProps = WithoutRouting<CreateOrganizationProps> & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 type UserProfileMode = 'modal' | 'navigation';
 type UserButtonProfileMode =
@@ -1918,7 +1959,14 @@ export type WaitlistProps = {
   signInUrl?: string;
 };
 
-export type WaitlistModalProps = WaitlistProps;
+export type WaitlistModalProps = WaitlistProps & {
+  /**
+   * Function that returns the container element where portals should be rendered.
+   * This allows Clerk components to render inside external dialogs/popovers
+   * (e.g., Radix Dialog, React Aria Components) instead of document.body.
+   */
+  getContainer?: () => HTMLElement | null;
+};
 
 type PricingTableDefaultProps = {
   /**

packages/tanstack-react-start/src/client/index.ts

@@ -1,2 +1,3 @@
 export * from './ClerkProvider';
 export { SignIn, SignUp, OrganizationProfile, OrganizationList, UserProfile } from './uiComponents';
+export { UNSAFE_PortalProvider } from '@clerk/react';