feat(clerk-js): Portal option

packages/clerk-js/src/ui/Components.tsx

@@ -463,6 +463,7 @@ const Components = (props: ComponentsProps) => {
       componentName={'UserProfileModal'}
       modalContainerSx={{ alignItems: 'center' }}
       modalContentSx={t => ({ height: `min(${t.sizes.$176}, calc(100% - ${t.sizes.$12}))`, margin: 0 })}
+      portal={(userProfileModal as UserProfileProps & { portal?: boolean | (() => HTMLElement | null) })?.portal}
     >
       <UserProfileModal {...userProfileModal} />
     </LazyModalRenderer>

packages/clerk-js/src/ui/components/OrganizationSwitcher/index.tsx

@@ -5,18 +5,27 @@ import { withCardStateProvider, withFloatingTree } from '@/ui/elements/contexts'
 import { Popover } from '@/ui/elements/Popover';
 
 import { AcceptedInvitationsProvider, useOrganizationSwitcherContext, withCoreUserGuard } from '../../contexts';
+import { usePortalContext } from '../../contexts/PortalContext';
 import { Flow } from '../../customizables';
 import { usePopover } from '../../hooks';
 import { OrganizationSwitcherPopover } from './OrganizationSwitcherPopover';
 import { OrganizationSwitcherTrigger } from './OrganizationSwitcherTrigger';
 
 const OrganizationSwitcherWithFloatingTree = withFloatingTree<{ children: ReactElement }>(({ children }) => {
-  const { defaultOpen } = useOrganizationSwitcherContext();
+  const { defaultOpen, portal: portalProp = true } = useOrganizationSwitcherContext();
+
+  // Get portal from context, fallback to prop, then default to true
+  const portalFromContext = usePortalContext();
+  const portal = portalProp !== undefined ? portalProp : (portalFromContext ?? true);
+
+  // Detect if custom portal is used (function or from context indicates intentional custom portal)
+  const useFixedPosition = typeof portal === 'function' || (portal !== false && portalFromContext !== undefined);
 
   const { floating, reference, styles, toggle, isOpen, nodeId, context } = usePopover({
     defaultOpen,
     placement: 'bottom-start',
     offset: 8,
+    strategy: useFixedPosition ? 'fixed' : 'absolute',
   });
 
   const switcherButtonMenuId = useId();
@@ -34,6 +43,7 @@ const OrganizationSwitcherWithFloatingTree = withFloatingTree<{ children: ReactE
         nodeId={nodeId}
         context={context}
         isOpen={isOpen}
+        portal={portal}
       >
         {cloneElement(children, {
           id: switcherButtonMenuId,

packages/clerk-js/src/ui/components/UserButton/index.tsx

@@ -4,18 +4,27 @@ import { withCardStateProvider, withFloatingTree } from '@/ui/elements/contexts'
 import { Popover } from '@/ui/elements/Popover';
 
 import { useUserButtonContext, withCoreUserGuard } from '../../contexts';
+import { usePortalContext } from '../../contexts/PortalContext';
 import { Flow } from '../../customizables';
 import { usePopover } from '../../hooks';
 import { UserButtonPopover } from './UserButtonPopover';
 import { UserButtonTrigger } from './UserButtonTrigger';
 
 const UserButtonWithFloatingTree = withFloatingTree<{ children: ReactElement }>(({ children }) => {
-  const { defaultOpen } = useUserButtonContext();
+  const { defaultOpen, portal: portalProp = true } = useUserButtonContext();
+
+  // Get portal from context, fallback to prop, then default to true
+  const portalFromContext = usePortalContext();
+  const portal = portalProp !== undefined ? portalProp : (portalFromContext ?? true);
+
+  // Detect if custom portal is used (function or from context indicates intentional custom portal)
+  const useFixedPosition = typeof portal === 'function' || (portal !== false && portalFromContext !== undefined);
 
   const { floating, reference, styles, toggle, isOpen, nodeId, context } = usePopover({
     defaultOpen,
     placement: 'bottom-end',
     offset: 8,
+    strategy: useFixedPosition ? 'fixed' : 'absolute',
   });
 
   const userButtonMenuId = useId();
@@ -33,6 +42,7 @@ const UserButtonWithFloatingTree = withFloatingTree<{ children: ReactElement }>(
         nodeId={nodeId}
         context={context}
         isOpen={isOpen}
+        portal={portal}
       >
         {cloneElement(children, {
           id: userButtonMenuId,

packages/clerk-js/src/ui/components/UserButton/useMultisessionActions.tsx

@@ -1,5 +1,10 @@
 import { useClerk } from '@clerk/shared/react';
-import type { SignedInSessionResource, UserButtonProps, UserResource } from '@clerk/shared/types';
+import type {
+  SignedInSessionResource,
+  UserButtonProps,
+  UserProfileModalProps,
+  UserResource,
+} from '@clerk/shared/types';
 
 import { navigateIfTaskExists } from '@/core/sessionTasks';
 import { useEnvironment } from '@/ui/contexts';
@@ -19,7 +24,7 @@ type UseMultisessionActionsParams = {
   userProfileUrl?: string;
   signInUrl?: string;
   taskUrl?: string | null;
-} & Pick<UserButtonProps, 'userProfileMode' | 'appearance' | 'userProfileProps'>;
+} & Pick<UserButtonProps, 'userProfileMode' | 'appearance' | 'userProfileProps' | 'portal'>;
 
 export const useMultisessionActions = (opts: UseMultisessionActionsParams) => {
   const { setActive, signOut, openUserProfile } = useClerk();
@@ -46,7 +51,10 @@ export const useMultisessionActions = (opts: UseMultisessionActionsParams) => {
         })();
       });
     }
-    openUserProfile(opts.userProfileProps);
+    openUserProfile({
+      ...opts.userProfileProps,
+      portal: opts.portal,
+    } as UserProfileModalProps);
     return opts.actionCompleteCallback?.();
   };
 
@@ -62,7 +70,8 @@ export const useMultisessionActions = (opts: UseMultisessionActionsParams) => {
     openUserProfile({
       ...opts.userProfileProps,
       ...(__experimental_startPath && { __experimental_startPath }),
-    });
+      portal: opts.portal,
+    } as UserProfileModalProps);
 
     return opts.actionCompleteCallback?.();
   };

packages/clerk-js/src/ui/contexts/PortalContext.tsx

@@ -0,0 +1,18 @@
+import type { PortalConfig } from '@clerk/shared/types';
+import React from 'react';
+
+const PortalContext = React.createContext<{ portal?: PortalConfig } | null>(null);
+
+interface PortalProviderProps {
+  children: React.ReactNode;
+  portal?: PortalConfig;
+}
+
+export function PortalProvider({ children, portal }: PortalProviderProps): JSX.Element {
+  return <PortalContext.Provider value={{ portal }}>{children}</PortalContext.Provider>;
+}
+
+export function usePortalContext(): PortalConfig | undefined {
+  const context = React.useContext(PortalContext);
+  return context?.portal;
+}

packages/clerk-js/src/ui/contexts/index.ts

@@ -6,3 +6,4 @@ export * from './CoreSessionContext';
 export * from './CoreClientContext';
 export * from './CoreClerkContextWrapper';
 export * from './AcceptedUserInvitations';
+export * from './PortalContext';

packages/clerk-js/src/ui/elements/Menu.tsx

@@ -1,11 +1,12 @@
 import { createContextAndHook } from '@clerk/shared/react';
-import type { MenuId } from '@clerk/shared/types';
+import type { MenuId, PortalConfig } from '@clerk/shared/types';
 import type { Placement } from '@floating-ui/react';
 import type { PropsWithChildren } from 'react';
 import React, { cloneElement, isValidElement, useLayoutEffect, useRef } from 'react';
 
 import type { Button } from '../customizables';
 import { Col, descriptors, SimpleButton } from '../customizables';
+import { usePortalContext } from '../contexts/PortalContext';
 import type { UsePopoverReturn } from '../hooks';
 import { usePopover } from '../hooks';
 import type { PropsOfComponent } from '../styledSystem';
@@ -28,10 +29,15 @@ type MenuProps = PropsWithChildren<Record<never, never>> & {
 
 export const Menu = withFloatingTree((props: MenuProps) => {
   const { popoverPlacement = 'bottom-end', elementId, ...rest } = props;
+  const portalFromContext = usePortalContext();
+  const useFixedPosition =
+    typeof portalFromContext === 'function' || (portalFromContext !== false && portalFromContext !== undefined);
+
   const popoverCtx = usePopover({
     placement: popoverPlacement,
     offset: 8,
     shoudFlip: true,
+    strategy: useFixedPosition ? 'fixed' : 'absolute',
   });
 
   const value = React.useMemo(() => ({ value: { popoverCtx, elementId } }), [{ ...popoverCtx }, elementId]);
@@ -82,15 +88,19 @@ const findMenuItem = (el: Element, siblingType: 'prev' | 'next', options?: { cou
 };
 
 type MenuListProps = PropsOfComponent<typeof Col> & {
-  asPortal?: boolean;
+  asPortal?: PortalConfig;
 };
 
 export const MenuList = (props: MenuListProps) => {
-  const { sx, asPortal, ...rest } = props;
+  const { sx, asPortal: asPortalProp, ...rest } = props;
   const { popoverCtx, elementId } = useMenuState();
   const { floating, styles, isOpen, context, nodeId } = popoverCtx;
   const containerRef = useRef<HTMLDivElement | null>(null);
 
+  // Get portal from context, fallback to prop, then default to false
+  const portalFromContext = usePortalContext();
+  const asPortal = asPortalProp !== undefined ? asPortalProp : (portalFromContext ?? false);
+
   useLayoutEffect(() => {
     const current = containerRef.current;
     floating(current);

packages/clerk-js/src/ui/elements/Modal.tsx

@@ -1,9 +1,11 @@
 import { createContextAndHook, useSafeLayoutEffect } from '@clerk/shared/react';
+import type { PortalConfig } from '@clerk/shared/types';
 import React, { useRef } from 'react';
 
 import { descriptors, Flex } from '../customizables';
 import { usePopover } from '../hooks';
 import { useScrollLock } from '../hooks/useScrollLock';
+import { usePortalContext } from '../contexts/PortalContext';
 import type { ThemableCssProp } from '../styledSystem';
 import { animations, mqu } from '../styledSystem';
 import { withFloatingTree } from './contexts';
@@ -19,12 +21,41 @@ type ModalProps = React.PropsWithChildren<{
   containerSx?: ThemableCssProp;
   canCloseModal?: boolean;
   style?: React.CSSProperties;
-  portalRoot?: HTMLElement | React.MutableRefObject<HTMLElement | null>;
+  portalRoot?: PortalConfig | HTMLElement | React.MutableRefObject<HTMLElement | null>;
 }>;
 
 export const Modal = withFloatingTree((props: ModalProps) => {
   const { disableScrollLock, enableScrollLock } = useScrollLock();
-  const { handleClose, handleOpen, contentSx, containerSx, canCloseModal, id, style, portalRoot } = props;
+  const {
+    handleClose,
+    handleOpen,
+    contentSx,
+    containerSx,
+    canCloseModal,
+    id,
+    style,
+    portalRoot: portalRootProp,
+  } = props;
+
+  // Get portal from context, fallback to prop, then default to true
+  const portalFromContext = usePortalContext();
+  const portalRoot = portalRootProp !== undefined ? portalRootProp : (portalFromContext ?? true);
+
+  // Resolve portal root
+  const resolvePortalRoot = (): HTMLElement | null => {
+    if (typeof portalRoot === 'function') {
+      return portalRoot();
+    }
+    if (typeof portalRoot === 'boolean') {
+      return null;
+    }
+    if (typeof portalRoot === 'object' && 'current' in portalRoot) {
+      return portalRoot.current;
+    }
+    return portalRoot || null;
+  };
+
+  const resolvedRoot = resolvePortalRoot();
   const overlayRef = useRef<HTMLDivElement>(null);
   const { floating, isOpen, context, nodeId, toggle } = usePopover({
     defaultOpen: true,
@@ -56,7 +87,8 @@ export const Modal = withFloatingTree((props: ModalProps) => {
       context={context}
       isOpen={isOpen}
       outsideElementsInert
-      root={portalRoot}
+      portal={resolvedRoot ? () => resolvedRoot : false}
+      root={resolvedRoot || undefined}
     >
       <ModalContext.Provider value={modalCtx}>
         <Flex

packages/clerk-js/src/ui/elements/Popover.tsx

@@ -1,8 +1,11 @@
+import type { PortalConfig } from '@clerk/shared/types';
 import type { FloatingContext, ReferenceType } from '@floating-ui/react';
 import { FloatingFocusManager, FloatingNode, FloatingPortal } from '@floating-ui/react';
 import type { PropsWithChildren } from 'react';
 import React from 'react';
 
+import { usePortalContext } from '../contexts/PortalContext';
+
 type PopoverProps = PropsWithChildren<{
   context: FloatingContext<ReferenceType>;
   nodeId?: string;
@@ -14,7 +17,7 @@ type PopoverProps = PropsWithChildren<{
    */
   outsideElementsInert?: boolean;
   order?: Array<'reference' | 'floating' | 'content'>;
-  portal?: boolean;
+  portal?: PortalConfig;
   /**
    * The root element to render the portal into.
    * @default document.body
@@ -30,41 +33,51 @@ export const Popover = (props: PopoverProps) => {
     order = ['reference', 'content'],
     nodeId,
     isOpen,
-    portal = true,
+    portal: portalProp,
     root,
     children,
   } = props;
 
-  if (portal) {
+  // Get portal from context, fallback to prop, then default to true
+  const portalFromContext = usePortalContext();
+  const portal = portalProp !== undefined ? portalProp : (portalFromContext ?? true);
+
+  // Resolve portal root
+  const resolveRoot = (): HTMLElement | null => {
+    if (typeof portal === 'function') {
+      return portal();
+    }
+    if (typeof root === 'object' && 'current' in root) {
+      return root.current;
+    }
+    return root || null;
+  };
+
+  const portalRoot = portal !== false ? resolveRoot() : null;
+  const shouldPortal = portal !== false && portalRoot !== null;
+
+  if (!isOpen) {
+    return <FloatingNode id={nodeId} />;
+  }
+
+  const content = (
+    <FloatingFocusManager
+      context={context}
+      initialFocus={initialFocus}
+      outsideElementsInert={outsideElementsInert}
+      order={order}
+    >
+      <>{children}</>
+    </FloatingFocusManager>
+  );
+
+  if (shouldPortal) {
     return (
       <FloatingNode id={nodeId}>
-        <FloatingPortal root={root}>
-          {isOpen && (
-            <FloatingFocusManager
-              context={context}
-              initialFocus={initialFocus}
-              outsideElementsInert={outsideElementsInert}
-              order={order}
-            >
-              <>{children}</>
-            </FloatingFocusManager>
-          )}
-        </FloatingPortal>
+        <FloatingPortal root={portalRoot}>{content}</FloatingPortal>
       </FloatingNode>
     );
   }
 
-  return (
-    <FloatingNode id={nodeId}>
-      {isOpen && (
-        <FloatingFocusManager
-          context={context}
-          initialFocus={initialFocus}
-          order={order}
-        >
-          <>{children}</>
-        </FloatingFocusManager>
-      )}
-    </FloatingNode>
-  );
+  return <FloatingNode id={nodeId}>{content}</FloatingNode>;
 };