react-magic-portal 1.1.8 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.2.0](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.9...v1.2.0) (2025-10-10)
+
+
+### Features
+
+* add root prop to customize MutationObserver scope ([e27aeeb](https://github.com/molvqingtai/react-magic-portal/commit/e27aeeb70ae2b93f9f6ac80d25deb436ca125065))
+
+
+### Performance Improvements
+
+* optimize node insertion with position check ([866947b](https://github.com/molvqingtai/react-magic-portal/commit/866947bba294d2887c30a9ce4670ecf6b5429b05))
+
+## [1.1.9](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.8...v1.1.9) (2025-10-09)
+
+
+### Bug Fixes
+
+* remove key prop from MagicPortal to prevent React warning ([2ac6cc1](https://github.com/molvqingtai/react-magic-portal/commit/2ac6cc1d91e33b3bb5e257ed0d36d5c546b2ccd9))
+
 ## [1.1.8](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.7...v1.1.8) (2025-09-30)
 
 

package/README.md

@@ -97,14 +97,14 @@ function App() {
 
 ### Props
 
-| Prop        | Type                                                                                       | Default      | Description                                                  |
-| ----------- | ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------ |
-| `anchor`    | `string \| (() => Element \| null) \| Element \| React.RefObject<Element \| null> \| null` | **Required** | The target element where the portal content will be rendered |
-| `position`  | `'append' \| 'prepend' \| 'before' \| 'after'`                                             | `'append'`   | Position relative to the anchor element                      |
-| `children`  | `React.ReactElement \| React.ReactElement[]`                                               | `undefined`  | The content to render in the portal                          |
-| `onMount`   | `(anchor: Element, container: Element) => void`                                            | `undefined`  | Callback fired when the portal is mounted                    |
-| `onUnmount` | `(anchor: Element, container: Element) => void`                                            | `undefined`  | Callback fired when the portal is unmounted                  |
-| `key`       | `React.Key`                                                                                | `undefined`  | Key for the ReactDOM.createPortal                            |
+| Prop        | Type                                                                                       | Default         | Description                                                  |
+| ----------- | ------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------ |
+| `anchor`    | `string \| (() => Element \| null) \| Element \| React.RefObject<Element \| null> \| null` | **Required**    | The target element where the portal content will be rendered |
+| `position`  | `'append' \| 'prepend' \| 'before' \| 'after'`                                             | `'append'`      | Position relative to the anchor element                      |
+| `root`      | `Element`                                                                                  | `document.body` | The root element to observe for DOM mutations                |
+| `children`  | `React.ReactElement \| React.ReactElement[]`                                               | `undefined`     | The content to render in the portal                          |
+| `onMount`   | `(anchor: Element, container: Element) => void`                                            | `undefined`     | Callback fired when the portal is mounted                    |
+| `onUnmount` | `(anchor: Element, container: Element) => void`                                            | `undefined`     | Callback fired when the portal is unmounted                  |
 
 ### Anchor Types
 

package/__tests__/eslint.config.ts

@@ -3,8 +3,7 @@ import pluginJs from '@eslint/js'
 import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 import prettierPlugin from 'eslint-plugin-prettier/recommended'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
+import eslintReact from '@eslint-react/eslint-plugin'
 
 export default defineConfig([
   {
@@ -18,13 +17,13 @@ export default defineConfig([
     }
   },
   pluginJs.configs.recommended,
-  ...tseslint.configs.recommended,
+  tseslint.configs.recommended,
+  eslintReact.configs['recommended-typescript'],
   prettierPlugin,
-  reactHooks.configs['recommended-latest'],
-  reactRefresh.configs.vite,
   {
     rules: {
-      '@typescript-eslint/no-explicit-any': 'off'
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@eslint-react/no-forward-ref': 'off'
     }
   }
 ])

package/__tests__/package.json

@@ -18,25 +18,24 @@
     "react-magic-portal": "workspace:*"
   },
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
+    "@eslint-react/eslint-plugin": "^2.0.6",
+    "@eslint/js": "^9.37.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.1.15",
-    "@types/react-dom": "^19.1.9",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
-    "happy-dom": "^19.0.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.45.0",
-    "vite": "^7.1.7",
+    "happy-dom": "^20.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^7.1.9",
     "vitest": "^3.2.4"
   }
 }

package/__tests__/src/magic-portal.test.tsx

@@ -47,7 +47,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowAnchor(true)}>Show Anchor</button>
+            <button type="button" onClick={() => setShowAnchor(true)}>
+              Show Anchor
+            </button>
             {showAnchor && <div id="dynamic-anchor">Anchor</div>}
             <MagicPortal anchor="#dynamic-anchor">
               <div data-testid="portal-content">Portal Content</div>
@@ -74,7 +76,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowAnchor(false)}>Hide Anchor</button>
+            <button type="button" onClick={() => setShowAnchor(false)}>
+              Hide Anchor
+            </button>
             {showAnchor && <div id="dynamic-anchor">Anchor</div>}
             <MagicPortal anchor="#dynamic-anchor">
               <div data-testid="portal-content">Portal Content</div>
@@ -435,22 +439,31 @@ describe('MagicPortal', () => {
 
     it('should work with forwardRef components as portal content', () => {
       const ForwardedComponent = React.forwardRef<HTMLButtonElement, { children: React.ReactNode }>(
-        ({ children }, ref) => <button ref={ref}>{children}</button>
+        ({ children }, forwardedRef) => (
+          <button type="button" ref={forwardedRef}>
+            {children}
+          </button>
+        )
       )
 
-      const buttonRef = vi.fn()
+      ForwardedComponent.displayName = 'ForwardedComponent'
+
+      const refCalls: Array<HTMLButtonElement | null> = []
+      const handleButtonRef: React.RefCallback<HTMLButtonElement> = (element) => {
+        refCalls.push(element)
+      }
       const anchor = document.createElement('div')
       anchor.id = 'forward-ref-anchor'
       document.body.appendChild(anchor)
 
       render(
         <MagicPortal anchor="#forward-ref-anchor">
-          <ForwardedComponent ref={buttonRef}>Click me</ForwardedComponent>
+          <ForwardedComponent ref={handleButtonRef}>Click me</ForwardedComponent>
         </MagicPortal>
       )
 
-      expect(buttonRef).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
-      expect(buttonRef.mock.calls[0][0]?.textContent).toBe('Click me')
+      expect(refCalls[0]).toBeInstanceOf(HTMLButtonElement)
+      expect(refCalls[0]?.textContent).toBe('Click me')
     })
 
     it('should handle single element content', () => {
@@ -527,7 +540,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowFirst(!showFirst)}>Toggle Content</button>
+            <button type="button" onClick={() => setShowFirst(!showFirst)}>
+              Toggle Content
+            </button>
             <MagicPortal anchor="#dynamic-content-anchor">
               {showFirst ? (
                 <div ref={ref1} data-testid="first-content">
@@ -601,7 +616,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={addElement}>Add Target Element</button>
+            <button type="button" onClick={addElement}>
+              Add Target Element
+            </button>
             <MagicPortal anchor=".dynamic-target">
               <div data-testid="portal-content">Portal Content</div>
             </MagicPortal>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-magic-portal",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "React Portal with dynamic mounting support",
   "main": "packages/component/dist/index.js",
   "type": "module",
@@ -40,7 +40,7 @@
   },
   "homepage": "https://github.com/molvqingtai/react-magic-portal#readme",
   "dependencies": {
-    "@commitlint/cli": "^20.0.0",
+    "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",

package/packages/component/dist/index.d.ts

@@ -4,19 +4,19 @@ import React from "react";
 interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null;
   position?: 'append' | 'prepend' | 'before' | 'after';
+  root?: Element;
   children?: React.ReactElement | React.ReactElement[];
   onMount?: (anchor: Element, container: Element) => void;
   onUnmount?: (anchor: Element, container: Element) => void;
-  key?: React.Key;
 }
 declare const MagicPortal: {
   ({
     anchor,
     position,
+    root,
     children,
     onMount,
-    onUnmount,
-    key
+    onUnmount
   }: MagicPortalProps): React.ReactPortal | null;
   displayName: string;
 };

package/packages/component/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;UAGiB,gBAAA;0BACS,kBAAkB,UAAU,KAAA,CAAM,UAAU;EADrD,QAAA,CAAA,EAAA,QAAgB,GAAA,SAAA,GAAA,QAAA,GAAA,OAAA;EAAA,QAAA,CAAA,EAGpB,KAAA,CAAM,YAHc,GAGC,KAAA,CAAM,YAHP,EAAA;SACP,CAAA,EAAA,CAAA,MAAA,EAGL,OAHK,EAAA,SAAA,EAGe,OAHf,EAAA,GAAA,IAAA;WAAkB,CAAA,EAAA,CAAA,MAAA,EAIrB,OAJqB,EAAA,SAAA,EAID,OAJC,EAAA,GAAA,IAAA;KAA0B,CAAA,EAK9D,KAAA,CAAM,GALwD;;cA4DhE,WA1Da,EAAA;;IAAe,MAAM;IAAA,QAAA;IAAA,QAAA;IAAA,OAAA;IAAA,SAAA;IAAA;EAAA,CAAA,EA0DiD,gBA1DjD,CAAA,EA0DiE,KAAA,CAAA,WA1DjE,GAAA,IAAA;aACnB,EAAA,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;UAGiB,gBAAA;0BACS,kBAAkB,UAAU,KAAA,CAAM,UAAU;EADrD,QAAA,CAAA,EAAA,QAAgB,GAAA,SAAA,GAAA,QAAA,GAAA,OAAA;EAAA,IAAA,CAAA,EAGxB,OAHwB;UACP,CAAA,EAGb,KAAA,CAAM,YAHO,GAGQ,KAAA,CAAM,YAHd,EAAA;SAAkB,CAAA,EAAA,CAAA,MAAA,EAIvB,OAJuB,EAAA,SAAA,EAIH,OAJG,EAAA,GAAA,IAAA;WAA0B,CAAA,EAAA,CAAA,MAAA,EAK/C,OAL+C,EAAA,SAAA,EAK3B,OAL2B,EAAA,GAAA,IAAA;;cA4DhE,WA1DG,EAAA;;IACI,MAAM;IAAA,QAAA;IAAA,IAAA;IAAA,QAAA;IAAA,OAAA;IAAA;EAAA,CAAA,EAgEhB,gBAhEgB,CAAA,EAgEA,KAAA,CAAA,WAhEA,GAAA,IAAA;aAAqB,EAAA,MAAA"}

package/packages/component/dist/index.js

@@ -1,2 +1,2 @@
-import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import{createPortal as o}from"react-dom";const s=e=>{let t=Object.getOwnPropertyDescriptor(e.props,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning;return n?e.ref:(t=Object.getOwnPropertyDescriptor(e,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning,n?e.props.ref:e.props.ref||e.ref)},c=e=>typeof e==`string`?document.querySelector(e):typeof e==`function`?e():e&&`current`in e?e.current:e,l=(e,t)=>{if(typeof e==`function`)return e(t);e!=null&&(e.current=t)},u=(...e)=>t=>{let n=e.map(e=>l(e,t));return()=>n.forEach((t,n)=>typeof t==`function`?t():l(e[n],null))},d=({anchor:l,position:d=`append`,children:f,onMount:p,onUnmount:m,key:h})=>{let g=i(null),[_,v]=a(null),y=e.Children.map(f,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:u(n,e=>{e&&g.current?.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[d],e)})})}),b=t(()=>{g.current=c(l),v(d===`prepend`||d===`append`?g.current:g.current?.parentElement??null)},[l,d]);return r(()=>{b();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>_?.contains(e))&&b()});return e.observe(document.body,{childList:!0,subtree:!0}),()=>e.disconnect()},[b,l,_]),n(()=>{if(_&&g.current)return p?.(g.current,_),()=>{m?.(g.current,_)}},[p,m,_]),_&&o(y,_,h)};d.displayName=`MagicPortal`;var f=d;export{f as default};
+import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import{createPortal as o}from"react-dom";const s=e=>{let t=Object.getOwnPropertyDescriptor(e.props,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning;return n?e.ref:(t=Object.getOwnPropertyDescriptor(e,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning,n?e.props.ref:e.props.ref||e.ref)},c=e=>typeof e==`string`?document.querySelector(e):typeof e==`function`?e():e&&`current`in e?e.current:e,l=(e,t)=>{if(typeof e==`function`)return e(t);e!=null&&(e.current=t)},u=(...e)=>t=>{let n=e.map(e=>l(e,t));return()=>n.forEach((t,n)=>typeof t==`function`?t():l(e[n],null))},d=({anchor:l,position:d=`append`,root:f=document.body,children:p,onMount:m,onUnmount:h})=>{let g=i(null),[_,v]=a(null),y=t(e=>{if(!e)return;let t=g.current;if(!t)return;let n=d===`prepend`||d===`append`?t:t.parentElement;if(!n)return;let r=e.parentElement===n;if(r)switch(d){case`append`:r=e===n.lastElementChild;break;case`prepend`:r=e===n.firstElementChild;break;case`before`:r=e.nextElementSibling===t;break;case`after`:r=e.previousElementSibling===t;break}r||t.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[d],e)},[d]),b=e.Children.map(p,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:u(n,y)})}),x=t(()=>{g.current=c(l),v(d===`prepend`||d===`append`?g.current:g.current?.parentElement??null)},[l,d]);return r(()=>{x();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>_?.contains(e))&&x()});return e.observe(f,{childList:!0,subtree:!0}),()=>e.disconnect()},[x,l,_,f]),n(()=>{if(_&&g.current)return m?.(g.current,_),()=>{h?.(g.current,_)}},[m,h,_]),_&&o(b,_)};d.displayName=`MagicPortal`;var f=d;export{f as default};
 //# sourceMappingURL=index.js.map

package/packages/component/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'\nimport { createPortal } from 'react-dom'\n\nexport interface MagicPortalProps {\n  anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null\n  position?: 'append' | 'prepend' | 'before' | 'after'\n  children?: React.ReactElement | React.ReactElement[]\n  onMount?: (anchor: Element, container: Element) => void\n  onUnmount?: (anchor: Element, container: Element) => void\n  key?: React.Key\n}\n\n/**\n * https://github.com/radix-ui/primitives/blob/36d954d3c1b41c96b1d2e875b93fc9362c8c09e6/packages/react/slot/src/slot.tsx#L166\n */\nconst getElementRef = (element: React.ReactElement) => {\n  // React <=18 in DEV\n  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element as any).ref as React.Ref<Element>\n  }\n  // React 19 in DEV\n  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element.props as { ref?: React.Ref<Element> }).ref\n  }\n\n  // Not DEV\n  return (element.props as { ref?: React.Ref<Element> }).ref || ((element as any).ref as React.Ref<Element>)\n}\n\nconst resolveAnchor = (anchor: MagicPortalProps['anchor']) => {\n  if (typeof anchor === 'string') {\n    return document.querySelector(anchor)\n  } else if (typeof anchor === 'function') {\n    return anchor()\n  } else if (anchor && 'current' in anchor) {\n    return anchor.current\n  } else {\n    return anchor\n  }\n}\n\n/**\n * https://github.com/facebook/react/blob/d91d28c8ba6fe7c96e651f82fc47c9d5481bf5f9/packages/react-reconciler/src/ReactFiberHooks.js#L2792\n */\nconst setRef = <T>(ref: React.Ref<T> | undefined, value: T) => {\n  if (typeof ref === 'function') {\n    return ref(value)\n  } else if (ref !== null && ref !== undefined) {\n    ref.current = value\n  }\n}\n\nconst mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[]) => {\n  return (node: T) => {\n    const cleanups = refs.map((ref) => setRef(ref, node))\n    return () =>\n      cleanups.forEach((cleanup, index) => (typeof cleanup === 'function' ? cleanup() : setRef(refs[index], null)))\n  }\n}\n\nconst MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount, key }: MagicPortalProps) => {\n  const anchorRef = useRef<Element | null>(null)\n  const [container, setContainer] = useState<Element | null>(null)\n\n  const nodes = React.Children.map(children, (item) => {\n    if (!React.isValidElement(item)) {\n      return null\n    }\n    const originalRef = getElementRef(item)\n    return React.cloneElement(item as React.ReactElement<any>, {\n      ref: mergeRef(originalRef, (node) => {\n        const positionMap = {\n          before: 'beforebegin',\n          prepend: 'afterbegin',\n          append: 'beforeend',\n          after: 'afterend'\n        } as const\n        node && anchorRef.current?.insertAdjacentElement(positionMap[position], node)\n      })\n    })\n  })\n\n  const update = useCallback(() => {\n    anchorRef.current = resolveAnchor(anchor)\n    setContainer(\n      position === 'prepend' || position === 'append' ? anchorRef.current : (anchorRef.current?.parentElement ?? null)\n    )\n  }, [anchor, position])\n\n  useLayoutEffect(() => {\n    update()\n\n    const observer = new MutationObserver((mutations) => {\n      const isSelfMutation = mutations\n        .flatMap(({ addedNodes, removedNodes }) => [...addedNodes, ...removedNodes])\n        .some((node) => container?.contains(node))\n      !isSelfMutation && update()\n    })\n\n    observer.observe(document.body, {\n      childList: true,\n      subtree: true\n    })\n    return () => observer.disconnect()\n  }, [update, anchor, container])\n\n  useEffect(() => {\n    if (container && anchorRef.current) {\n      onMount?.(anchorRef.current, container)\n      return () => {\n        onUnmount?.(anchorRef.current!, container)\n      }\n    }\n  }, [onMount, onUnmount, container])\n\n  return container && createPortal(nodes, container, key)\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"8IAeA,MAAM,EAAiB,GAAgC,CAErD,IAAI,EAAS,OAAO,yBAAyB,EAAQ,MAAO,MAAM,EAAE,IAChE,EAAU,GAAU,mBAAoB,GAAU,EAAO,eAY7D,OAXI,EACM,EAAgB,KAG1B,EAAS,OAAO,yBAAyB,EAAS,MAAM,EAAE,IAC1D,EAAU,GAAU,mBAAoB,GAAU,EAAO,eACrD,EACM,EAAQ,MAAuC,IAIjD,EAAQ,MAAuC,KAAS,EAAgB,MAG5E,EAAiB,GACjB,OAAO,GAAW,SACb,SAAS,cAAc,EAAO,CAC5B,OAAO,GAAW,WACpB,GAAQ,CACN,GAAU,YAAa,EACzB,EAAO,QAEP,EAOL,GAAa,EAA+B,IAAa,CAC7D,GAAI,OAAO,GAAQ,WACjB,OAAO,EAAI,EAAM,CACR,GAAQ,OACjB,EAAI,QAAU,IAIZ,GAAsC,GAAG,IACrC,GAAY,CAClB,IAAM,EAAW,EAAK,IAAK,GAAQ,EAAO,EAAK,EAAK,CAAC,CACrD,UACE,EAAS,SAAS,EAAS,IAAW,OAAO,GAAY,WAAa,GAAS,CAAG,EAAO,EAAK,GAAQ,KAAK,CAAE,EAI7G,GAAe,CAAE,SAAQ,WAAW,SAAU,WAAU,UAAS,YAAW,SAA4B,CAC5G,IAAM,EAAY,EAAuB,KAAK,CACxC,CAAC,EAAW,GAAgB,EAAyB,KAAK,CAE1D,EAAQ,EAAM,SAAS,IAAI,EAAW,GAAS,CACnD,GAAI,CAAC,EAAM,eAAe,EAAK,CAC7B,OAAO,KAET,IAAM,EAAc,EAAc,EAAK,CACvC,OAAO,EAAM,aAAa,EAAiC,CACzD,IAAK,EAAS,EAAc,GAAS,CAOnC,GAAQ,EAAU,SAAS,sBANP,CAClB,OAAQ,cACR,QAAS,aACT,OAAQ,YACR,MAAO,WACR,CAC4D,GAAW,EAAK,EAC7E,CACH,CAAC,EACF,CAEI,EAAS,MAAkB,CAC/B,EAAU,QAAU,EAAc,EAAO,CACzC,EACE,IAAa,WAAa,IAAa,SAAW,EAAU,QAAW,EAAU,SAAS,eAAiB,KAC5G,EACA,CAAC,EAAQ,EAAS,CAAC,CA4BtB,OA1BA,MAAsB,CACpB,GAAQ,CAER,IAAM,EAAW,IAAI,iBAAkB,GAAc,CAInD,CAHuB,EACpB,SAAS,CAAE,aAAY,kBAAmB,CAAC,GAAG,EAAY,GAAG,EAAa,CAAC,CAC3E,KAAM,GAAS,GAAW,SAAS,EAAK,CAAC,EACzB,GAAQ,EAC3B,CAMF,OAJA,EAAS,QAAQ,SAAS,KAAM,CAC9B,UAAW,GACX,QAAS,GACV,CAAC,KACW,EAAS,YAAY,EACjC,CAAC,EAAQ,EAAQ,EAAU,CAAC,CAE/B,MAAgB,CACd,GAAI,GAAa,EAAU,QAEzB,OADA,IAAU,EAAU,QAAS,EAAU,KAC1B,CACX,IAAY,EAAU,QAAU,EAAU,GAG7C,CAAC,EAAS,EAAW,EAAU,CAAC,CAE5B,GAAa,EAAa,EAAO,EAAW,EAAI,EAGzD,EAAY,YAAc,cAE1B,IAAA,EAAe"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'\nimport { createPortal } from 'react-dom'\n\nexport interface MagicPortalProps {\n  anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null\n  position?: 'append' | 'prepend' | 'before' | 'after'\n  root?: Element\n  children?: React.ReactElement | React.ReactElement[]\n  onMount?: (anchor: Element, container: Element) => void\n  onUnmount?: (anchor: Element, container: Element) => void\n}\n\n/**\n * https://github.com/radix-ui/primitives/blob/36d954d3c1b41c96b1d2e875b93fc9362c8c09e6/packages/react/slot/src/slot.tsx#L166\n */\nconst getElementRef = (element: React.ReactElement) => {\n  // React <=18 in DEV\n  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element as any).ref as React.Ref<Element>\n  }\n  // React 19 in DEV\n  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element.props as { ref?: React.Ref<Element> }).ref\n  }\n\n  // Not DEV\n  return (element.props as { ref?: React.Ref<Element> }).ref || ((element as any).ref as React.Ref<Element>)\n}\n\nconst resolveAnchor = (anchor: MagicPortalProps['anchor']) => {\n  if (typeof anchor === 'string') {\n    return document.querySelector(anchor)\n  } else if (typeof anchor === 'function') {\n    return anchor()\n  } else if (anchor && 'current' in anchor) {\n    return anchor.current\n  } else {\n    return anchor\n  }\n}\n\n/**\n * https://github.com/facebook/react/blob/d91d28c8ba6fe7c96e651f82fc47c9d5481bf5f9/packages/react-reconciler/src/ReactFiberHooks.js#L2792\n */\nconst setRef = <T>(ref: React.Ref<T> | undefined, value: T) => {\n  if (typeof ref === 'function') {\n    return ref(value)\n  } else if (ref !== null && ref !== undefined) {\n    ref.current = value\n  }\n}\n\nconst mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[]) => {\n  return (node: T) => {\n    const cleanups = refs.map((ref) => setRef(ref, node))\n    return () =>\n      cleanups.forEach((cleanup, index) => (typeof cleanup === 'function' ? cleanup() : setRef(refs[index], null)))\n  }\n}\n\nconst MagicPortal = ({\n  anchor,\n  position = 'append',\n  root = document.body,\n  children,\n  onMount,\n  onUnmount\n}: MagicPortalProps) => {\n  const anchorRef = useRef<Element | null>(null)\n  const [container, setContainer] = useState<Element | null>(null)\n\n  const insertNode = useCallback(\n    (node: Element | null) => {\n      if (!node) {\n        return\n      }\n\n      const anchorElement = anchorRef.current\n      if (!anchorElement) {\n        return\n      }\n\n      const containerElement =\n        position === 'prepend' || position === 'append' ? anchorElement : anchorElement.parentElement\n      if (!containerElement) {\n        return\n      }\n\n      let alreadyPlaced = node.parentElement === containerElement\n\n      if (alreadyPlaced) {\n        switch (position) {\n          case 'append':\n            alreadyPlaced = node === containerElement.lastElementChild\n            break\n          case 'prepend':\n            alreadyPlaced = node === containerElement.firstElementChild\n            break\n          case 'before':\n            alreadyPlaced = node.nextElementSibling === anchorElement\n            break\n          case 'after':\n            alreadyPlaced = node.previousElementSibling === anchorElement\n            break\n        }\n      }\n\n      if (!alreadyPlaced) {\n        const positionMap = {\n          before: 'beforebegin',\n          prepend: 'afterbegin',\n          append: 'beforeend',\n          after: 'afterend'\n        } as const\n        anchorElement.insertAdjacentElement(positionMap[position], node)\n      }\n    },\n    [position]\n  )\n\n  const nodes = React.Children.map(children, (item) => {\n    if (!React.isValidElement(item)) {\n      return null\n    }\n    const originalRef = getElementRef(item)\n    return React.cloneElement(item as React.ReactElement<any>, {\n      ref: mergeRef(originalRef, insertNode)\n    })\n  })\n\n  const update = useCallback(() => {\n    anchorRef.current = resolveAnchor(anchor)\n    setContainer(\n      position === 'prepend' || position === 'append' ? anchorRef.current : (anchorRef.current?.parentElement ?? null)\n    )\n  }, [anchor, position])\n\n  useLayoutEffect(() => {\n    update()\n\n    const observer = new MutationObserver((mutations) => {\n      const isSelfMutation = mutations\n        .flatMap(({ addedNodes, removedNodes }) => [...addedNodes, ...removedNodes])\n        .some((node) => container?.contains(node))\n      !isSelfMutation && update()\n    })\n\n    observer.observe(root, {\n      childList: true,\n      subtree: true\n    })\n    return () => observer.disconnect()\n  }, [update, anchor, container, root])\n\n  useEffect(() => {\n    if (container && anchorRef.current) {\n      onMount?.(anchorRef.current, container)\n      return () => {\n        onUnmount?.(anchorRef.current!, container)\n      }\n    }\n  }, [onMount, onUnmount, container])\n\n  return container && createPortal(nodes, container)\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"8IAeA,MAAM,EAAiB,GAAgC,CAErD,IAAI,EAAS,OAAO,yBAAyB,EAAQ,MAAO,MAAM,EAAE,IAChE,EAAU,GAAU,mBAAoB,GAAU,EAAO,eAY7D,OAXI,EACM,EAAgB,KAG1B,EAAS,OAAO,yBAAyB,EAAS,MAAM,EAAE,IAC1D,EAAU,GAAU,mBAAoB,GAAU,EAAO,eACrD,EACM,EAAQ,MAAuC,IAIjD,EAAQ,MAAuC,KAAS,EAAgB,MAG5E,EAAiB,GACjB,OAAO,GAAW,SACb,SAAS,cAAc,EAAO,CAC5B,OAAO,GAAW,WACpB,GAAQ,CACN,GAAU,YAAa,EACzB,EAAO,QAEP,EAOL,GAAa,EAA+B,IAAa,CAC7D,GAAI,OAAO,GAAQ,WACjB,OAAO,EAAI,EAAM,CACR,GAAQ,OACjB,EAAI,QAAU,IAIZ,GAAsC,GAAG,IACrC,GAAY,CAClB,IAAM,EAAW,EAAK,IAAK,GAAQ,EAAO,EAAK,EAAK,CAAC,CACrD,UACE,EAAS,SAAS,EAAS,IAAW,OAAO,GAAY,WAAa,GAAS,CAAG,EAAO,EAAK,GAAQ,KAAK,CAAE,EAI7G,GAAe,CACnB,SACA,WAAW,SACX,OAAO,SAAS,KAChB,WACA,UACA,eACsB,CACtB,IAAM,EAAY,EAAuB,KAAK,CACxC,CAAC,EAAW,GAAgB,EAAyB,KAAK,CAE1D,EAAa,EAChB,GAAyB,CACxB,GAAI,CAAC,EACH,OAGF,IAAM,EAAgB,EAAU,QAChC,GAAI,CAAC,EACH,OAGF,IAAM,EACJ,IAAa,WAAa,IAAa,SAAW,EAAgB,EAAc,cAClF,GAAI,CAAC,EACH,OAGF,IAAI,EAAgB,EAAK,gBAAkB,EAE3C,GAAI,EACF,OAAQ,EAAR,CACE,IAAK,SACH,EAAgB,IAAS,EAAiB,iBAC1C,MACF,IAAK,UACH,EAAgB,IAAS,EAAiB,kBAC1C,MACF,IAAK,SACH,EAAgB,EAAK,qBAAuB,EAC5C,MACF,IAAK,QACH,EAAgB,EAAK,yBAA2B,EAChD,MAID,GAOH,EAAc,sBANM,CAClB,OAAQ,cACR,QAAS,aACT,OAAQ,YACR,MAAO,WACR,CAC+C,GAAW,EAAK,EAGpE,CAAC,EAAS,CACX,CAEK,EAAQ,EAAM,SAAS,IAAI,EAAW,GAAS,CACnD,GAAI,CAAC,EAAM,eAAe,EAAK,CAC7B,OAAO,KAET,IAAM,EAAc,EAAc,EAAK,CACvC,OAAO,EAAM,aAAa,EAAiC,CACzD,IAAK,EAAS,EAAa,EAAW,CACvC,CAAC,EACF,CAEI,EAAS,MAAkB,CAC/B,EAAU,QAAU,EAAc,EAAO,CACzC,EACE,IAAa,WAAa,IAAa,SAAW,EAAU,QAAW,EAAU,SAAS,eAAiB,KAC5G,EACA,CAAC,EAAQ,EAAS,CAAC,CA4BtB,OA1BA,MAAsB,CACpB,GAAQ,CAER,IAAM,EAAW,IAAI,iBAAkB,GAAc,CAInD,CAHuB,EACpB,SAAS,CAAE,aAAY,kBAAmB,CAAC,GAAG,EAAY,GAAG,EAAa,CAAC,CAC3E,KAAM,GAAS,GAAW,SAAS,EAAK,CAAC,EACzB,GAAQ,EAC3B,CAMF,OAJA,EAAS,QAAQ,EAAM,CACrB,UAAW,GACX,QAAS,GACV,CAAC,KACW,EAAS,YAAY,EACjC,CAAC,EAAQ,EAAQ,EAAW,EAAK,CAAC,CAErC,MAAgB,CACd,GAAI,GAAa,EAAU,QAEzB,OADA,IAAU,EAAU,QAAS,EAAU,KAC1B,CACX,IAAY,EAAU,QAAU,EAAU,GAG7C,CAAC,EAAS,EAAW,EAAU,CAAC,CAE5B,GAAa,EAAa,EAAO,EAAU,EAGpD,EAAY,YAAc,cAE1B,IAAA,EAAe"}

package/packages/component/eslint.config.ts

@@ -1,12 +1,12 @@
 import globals from 'globals'
+import type { Linter } from 'eslint'
 import pluginJs from '@eslint/js'
 import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 import prettierPlugin from 'eslint-plugin-prettier/recommended'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
+import eslintReact from '@eslint-react/eslint-plugin'
 
-export default defineConfig([
+const config: Linter.FlatConfig[] = defineConfig([
   {
     ignores: ['**/dist/*']
   },
@@ -18,14 +18,18 @@ export default defineConfig([
     }
   },
   pluginJs.configs.recommended,
-  ...tseslint.configs.recommended,
+  tseslint.configs.recommended,
+  eslintReact.configs['recommended-typescript'],
   prettierPlugin,
-  reactHooks.configs['recommended-latest'],
-  reactRefresh.configs.vite,
   {
     rules: {
       '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/no-unused-expressions': 'off'
+      '@typescript-eslint/no-unused-expressions': 'off',
+      '@eslint-react/no-children-map': 'off',
+      '@eslint-react/no-clone-element': 'off',
+      '@eslint-react/hooks-extra/no-direct-set-state-in-use-effect': 'off'
     }
   }
 ])
+
+export default config

package/packages/component/package.json

@@ -29,22 +29,21 @@
   },
   "homepage": "https://github.com/molvqingtai/react-magic-portal#readme",
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
-    "@types/node": "^24.6.0",
-    "@types/react": "^19.1.15",
-    "@types/react-dom": "^19.1.9",
-    "eslint": "^9.36.0",
+    "@eslint-react/eslint-plugin": "^2.0.6",
+    "@eslint/js": "^9.37.0",
+    "@types/node": "^24.7.1",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "eslint": "^9.37.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "tsdown": "^0.15.5",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.45.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsdown": "^0.15.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/packages/component/src/index.ts

@@ -4,10 +4,10 @@ import { createPortal } from 'react-dom'
 export interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null
   position?: 'append' | 'prepend' | 'before' | 'after'
+  root?: Element
   children?: React.ReactElement | React.ReactElement[]
   onMount?: (anchor: Element, container: Element) => void
   onUnmount?: (anchor: Element, container: Element) => void
-  key?: React.Key
 }
 
 /**
@@ -62,25 +62,73 @@ const mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[
   }
 }
 
-const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount, key }: MagicPortalProps) => {
+const MagicPortal = ({
+  anchor,
+  position = 'append',
+  root = document.body,
+  children,
+  onMount,
+  onUnmount
+}: MagicPortalProps) => {
   const anchorRef = useRef<Element | null>(null)
   const [container, setContainer] = useState<Element | null>(null)
 
-  const nodes = React.Children.map(children, (item) => {
-    if (!React.isValidElement(item)) {
-      return null
-    }
-    const originalRef = getElementRef(item)
-    return React.cloneElement(item as React.ReactElement<any>, {
-      ref: mergeRef(originalRef, (node) => {
+  const insertNode = useCallback(
+    (node: Element | null) => {
+      if (!node) {
+        return
+      }
+
+      const anchorElement = anchorRef.current
+      if (!anchorElement) {
+        return
+      }
+
+      const containerElement =
+        position === 'prepend' || position === 'append' ? anchorElement : anchorElement.parentElement
+      if (!containerElement) {
+        return
+      }
+
+      let alreadyPlaced = node.parentElement === containerElement
+
+      if (alreadyPlaced) {
+        switch (position) {
+          case 'append':
+            alreadyPlaced = node === containerElement.lastElementChild
+            break
+          case 'prepend':
+            alreadyPlaced = node === containerElement.firstElementChild
+            break
+          case 'before':
+            alreadyPlaced = node.nextElementSibling === anchorElement
+            break
+          case 'after':
+            alreadyPlaced = node.previousElementSibling === anchorElement
+            break
+        }
+      }
+
+      if (!alreadyPlaced) {
         const positionMap = {
           before: 'beforebegin',
           prepend: 'afterbegin',
           append: 'beforeend',
           after: 'afterend'
         } as const
-        node && anchorRef.current?.insertAdjacentElement(positionMap[position], node)
-      })
+        anchorElement.insertAdjacentElement(positionMap[position], node)
+      }
+    },
+    [position]
+  )
+
+  const nodes = React.Children.map(children, (item) => {
+    if (!React.isValidElement(item)) {
+      return null
+    }
+    const originalRef = getElementRef(item)
+    return React.cloneElement(item as React.ReactElement<any>, {
+      ref: mergeRef(originalRef, insertNode)
     })
   })
 
@@ -101,12 +149,12 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
       !isSelfMutation && update()
     })
 
-    observer.observe(document.body, {
+    observer.observe(root, {
       childList: true,
       subtree: true
     })
     return () => observer.disconnect()
-  }, [update, anchor, container])
+  }, [update, anchor, container, root])
 
   useEffect(() => {
     if (container && anchorRef.current) {
@@ -117,7 +165,7 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
     }
   }, [onMount, onUnmount, container])
 
-  return container && createPortal(nodes, container, key)
+  return container && createPortal(nodes, container)
 }
 
 MagicPortal.displayName = 'MagicPortal'

package/packages/example/eslint.config.ts

@@ -3,8 +3,7 @@ import pluginJs from '@eslint/js'
 import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 import prettierPlugin from 'eslint-plugin-prettier/recommended'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
+import eslintReact from '@eslint-react/eslint-plugin'
 
 export default defineConfig([
   {
@@ -18,8 +17,7 @@ export default defineConfig([
     }
   },
   pluginJs.configs.recommended,
-  ...tseslint.configs.recommended,
-  prettierPlugin,
-  reactHooks.configs['recommended-latest'],
-  reactRefresh.configs.vite
+  tseslint.configs.recommended,
+  eslintReact.configs['recommended-typescript'],
+  prettierPlugin
 ])

package/packages/example/package.json

@@ -11,22 +11,21 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-magic-portal": "workspace:*"
   },
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
-    "@types/react": "^19.1.15",
-    "@types/react-dom": "^19.1.9",
+    "@eslint-react/eslint-plugin": "^2.0.6",
+    "@eslint/js": "^9.37.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
     "@vitejs/plugin-react": "^5.0.4",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
-    "typescript": "~5.9.2",
-    "typescript-eslint": "^8.45.0",
-    "vite": "^7.1.7"
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^7.1.9"
   }
 }

package/packages/example/src/App.tsx

@@ -27,7 +27,9 @@ function App() {
         )}
       </div>
       <div className="controls">
-        <button onClick={() => setShowAnchor(!showAnchor)}>{showAnchor ? 'Hide Anchor' : 'Show Anchor'}</button>
+        <button type="button" onClick={() => setShowAnchor(!showAnchor)}>
+          {showAnchor ? 'Hide Anchor' : 'Show Anchor'}
+        </button>
       </div>
 
       {/* Target anchor examples */}