preactjs · rschristian · Sep 30, 2025 · Sep 30, 2025 · rschristian · Sep 30, 2025
diff --git a/content/en/guide/v10/api-reference.md b/content/en/guide/v10/api-reference.md
@@ -69,9 +69,22 @@ render(<Foo />, document.getElementById('container'));
 // </div>
 ```
 
-If the optional `replaceNode` parameter is provided, it must be a child of `containerNode`. Instead of inferring where to start rendering, Preact will update or replace the passed element using its diffing algorithm.
+The first argument must be a valid Virtual DOM Element, which represents either a component or an element. When passing a Component, it's important to let Preact do the instantiation rather than invoking your component directly, which will break in unexpected ways:
+
+```jsx
+const App = () => <div>foo</div>;
+
+// DON'T: Invoking components directly means they won't be counted as a
+// VNode and hence not be able to use functionality relating to vnodes.
+render(App(), rootElement); // ERROR
+render(App, rootElement); // ERROR
+
+// DO: Passing components using h() or JSX allows Preact to render correctly:
+render(h(App), rootElement); // success
+render(<App />, rootElement); // success
+```
 
-> ⚠️ The `replaceNode`-argument will be removed with Preact `v11`. It introduces too many edge cases and bugs which need to be accounted for in the rest of Preact's source code. We're leaving this section up for historical reasons, but we don't recommend anyone to use the third `replaceNode` argument.
+If the optional `replaceNode` parameter is provided, it must be a child of `containerNode`. Instead of inferring where to start rendering, Preact will update or replace the passed element using its diffing algorithm.
 
 ```jsx
 // DOM tree before render:
@@ -97,20 +110,7 @@ render(
 // </div>
 ```
 
-The first argument must be a valid Virtual DOM Element, which represents either a component or an element. When passing a Component, it's important to let Preact do the instantiation rather than invoking your component directly, which will break in unexpected ways:
-
-```jsx
-const App = () => <div>foo</div>;
-
-// DON'T: Invoking components directly means they won't be counted as a
-// VNode and hence not be able to use functionality relating to vnodes.
-render(App(), rootElement); // ERROR
-render(App, rootElement); // ERROR
-
-// DO: Passing components using h() or JSX allows Preact to render correctly:
-render(h(App), rootElement); // success
-render(<App />, rootElement); // success
-```
+> ⚠️ The `replaceNode`-argument will be removed with Preact `v11`. It introduces too many edge cases and bugs which need to be accounted for in the rest of Preact's source code. If you still need this functionality, we recommend using [`preact-root-fragment`](/guide/v10/preact-root-fragment), a small helper library that provides similar functionality. It is compatible with both Preact `v10` and `v11`.
 
 ## hydrate()
 

diff --git a/content/en/guide/v10/preact-root-fragment.md b/content/en/guide/v10/preact-root-fragment.md
@@ -0,0 +1,102 @@
+---
+title: preact-root-fragment
+description: A standalone Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10
+---
+
+# preact-root-fragment
+
+preact-root-fragment is a standalone and more flexible Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10.
+
+It provides a way to render or hydrate a Preact tree using a subset of the children within the parent element passed to render():
+
+```html
+<body>
+	<div id="root"> ⬅ we pass this to render() as the parent DOM element...
+
+		<script src="/etc.js"></script>
+
+		<div class="app"> ⬅ ... but we want to use this tree, not the script
+			<!-- ... -->
+		</div>
+	</div>
+</body>
+```
+
+---
+
+<toc></toc>
+
+---
+
+## Why do I need this?
+
+This is particularly useful for [partial hydration](https://jasonformat.com/islands-architecture/), which often requires rendering multiple distinct Preact trees into the same parent DOM element. Imagine the scenario below - which elements would we pass to `hydrate(jsx, parent)` such that each widget's `<section>` would get hydrated without clobbering the others?
+
+```html
+<div id="sidebar">
+  <section id="widgetA"><h1>Widget A</h1></section>
+  <section id="widgetB"><h1>Widget B</h1></section>
+  <section id="widgetC"><h1>Widget C</h1></section>
+</div>
+```
+
+Preact 10 provided a somewhat obscure third argument for `render` and `hydrate` called `replaceNode`, which could be used for the above case:
+
+```jsx
+render(<A />, sidebar, widgetA); // render into <div id="sidebar">, but only look at <section id="widgetA">
+render(<B />, sidebar, widgetB); // same, but only look at widgetB
+render(<C />, sidebar, widgetC); // same, but only look at widgetC
+```
+
+While the `replaceNode` argument proved useful for handling scenarios like the above, it was limited to a single DOM element and could not accommodate Preact trees with multiple root elements. It also didn't handle updates well when multiple trees were mounted into the same parent DOM element, which turns out to be a key usage scenario.
+
+Going forward, we're providing this functionality as a standalone library called `preact-root-fragment`.
+
+## How it works
+
+`preact-root-fragment` provides a `createRootFragment` function:
+
+```ts
+createRootFragment(parent: ContainerNode, children: ContainerNode | ContainerNode[]);
+```
+
+Calling this function with a parent DOM element and one or more child elements returns a "Persistent Fragment". A persistent fragment is a fake DOM element, which pretends to contain the provided children while keeping them in their existing real parent element. It can be passed to `render()` or `hydrate()` instead of the `parent` argument.
+
+Using the previous example, we can change the deprecated `replaceNode` usage out for `createRootFragment`:
+
+```jsx
+import { createRootFragment } from 'preact-root-fragment';
+
+render(<A />, createRootFragment(sidebar, widgetA));
+render(<B />, createRootFragment(sidebar, widgetB));
+render(<C />, createRootFragment(sidebar, widgetC));
+```
+
+Since we're creating separate "Persistent Fragment" parents to pass to each `render()` call, Preact will treat each as an independent Virtual DOM tree.
+
+## Multiple Root Elements
+
+Unlike the `replaceNode` parameter from Preact 10, `createRootFragment` can accept an Array of children that will be used as the root elements when rendering. This is particularly useful when rendering a Virtual DOM tree that produces multiple root elements, such as a Fragment or an Array:
+
+```jsx
+import { createRootFragment } from 'preact-root-fragment';
+import { render } from 'preact';
+
+function App() {
+  return (
+    <>
+      <h1>Example</h1>
+      <p>Hello world!</p>
+    </>
+  );
+}
+
+// Use only the last two child elements within <body>:
+const children = [].slice.call(document.body.children, -2);
+
+render(<App />, createRootFragment(document.body, children));
+```
+
+## Preact Version Support
+
+This library works with Preact 10 and 11.
diff --git a/content/en/guide/v11/preact-root-fragment.md b/content/en/guide/v11/preact-root-fragment.md
@@ -0,0 +1,102 @@
+---
+title: preact-root-fragment
+description: A standalone Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10
+---
+
+# preact-root-fragment
+
+preact-root-fragment is a standalone and more flexible Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10.
+
+It provides a way to render or hydrate a Preact tree using a subset of the children within the parent element passed to render():
+
+```html
+<body>
+	<div id="root"> ⬅ we pass this to render() as the parent DOM element...
+
+		<script src="/etc.js"></script>
+
+		<div class="app"> ⬅ ... but we want to use this tree, not the script
+			<!-- ... -->
+		</div>
+	</div>
+</body>
+```
+
+---
+
+<toc></toc>
+
+---
+
+## Why do I need this?
+
+This is particularly useful for [partial hydration](https://jasonformat.com/islands-architecture/), which often requires rendering multiple distinct Preact trees into the same parent DOM element. Imagine the scenario below - which elements would we pass to `hydrate(jsx, parent)` such that each widget's `<section>` would get hydrated without clobbering the others?
+
+```html
+<div id="sidebar">
+  <section id="widgetA"><h1>Widget A</h1></section>
+  <section id="widgetB"><h1>Widget B</h1></section>
+  <section id="widgetC"><h1>Widget C</h1></section>
+</div>
+```
+
+Preact 10 provided a somewhat obscure third argument for `render` and `hydrate` called `replaceNode`, which could be used for the above case:
+
+```jsx
+render(<A />, sidebar, widgetA); // render into <div id="sidebar">, but only look at <section id="widgetA">
+render(<B />, sidebar, widgetB); // same, but only look at widgetB
+render(<C />, sidebar, widgetC); // same, but only look at widgetC
+```
+
+While the `replaceNode` argument proved useful for handling scenarios like the above, it was limited to a single DOM element and could not accommodate Preact trees with multiple root elements. It also didn't handle updates well when multiple trees were mounted into the same parent DOM element, which turns out to be a key usage scenario.
+
+Going forward, we're providing this functionality as a standalone library called `preact-root-fragment`.
+
+## How it works
+
+`preact-root-fragment` provides a `createRootFragment` function:
+
+```ts
+createRootFragment(parent: ContainerNode, children: ContainerNode | ContainerNode[]);
+```
+
+Calling this function with a parent DOM element and one or more child elements returns a "Persistent Fragment". A persistent fragment is a fake DOM element, which pretends to contain the provided children while keeping them in their existing real parent element. It can be passed to `render()` or `hydrate()` instead of the `parent` argument.
+
+Using the previous example, we can change the deprecated `replaceNode` usage out for `createRootFragment`:
+
+```jsx
+import { createRootFragment } from 'preact-root-fragment';
+
+render(<A />, createRootFragment(sidebar, widgetA));
+render(<B />, createRootFragment(sidebar, widgetB));
+render(<C />, createRootFragment(sidebar, widgetC));
+```
+
+Since we're creating separate "Persistent Fragment" parents to pass to each `render()` call, Preact will treat each as an independent Virtual DOM tree.
+
+## Multiple Root Elements
+
+Unlike the `replaceNode` parameter from Preact 10, `createRootFragment` can accept an Array of children that will be used as the root elements when rendering. This is particularly useful when rendering a Virtual DOM tree that produces multiple root elements, such as a Fragment or an Array:
+
+```jsx
+import { createRootFragment } from 'preact-root-fragment';
+import { render } from 'preact';
+
+function App() {
+  return (
+    <>
+      <h1>Example</h1>
+      <p>Hello world!</p>
+    </>
+  );
+}
+
+// Use only the last two child elements within <body>:
+const children = [].slice.call(document.body.children, -2);
+
+render(<App />, createRootFragment(document.body, children));
+```
+
+## Preact Version Support
+
+This library works with Preact 10 and 11.
diff --git a/src/config.json b/src/config.json
@@ -471,6 +471,33 @@
 						}
 					}
 				]
+			},
+			{
+				"name": {
+					"en": "Libraries",
+					"ru": "Библиотеки",
+					"zh": "库"
+				},
+				"routes": [
+					{
+						"path": "/preact-iso",
+						"name": {
+							"en": "preact-iso"
+						}
+					},
+					{
+						"path": "/preact-custom-element",
+						"name": {
+							"en": "preact-custom-element"
+						}
+					},
+					{
+						"path": "/preact-root-fragment",
+						"name": {
+							"en": "preact-root-fragment"
+						}
+					}
+				]
 			}
 		],
 		"v10": [
@@ -767,6 +794,12 @@
 						"name": {
 							"en": "preact-custom-element"
 						}
+					},
+					{
+						"path": "/preact-root-fragment",
+						"name": {
+							"en": "preact-root-fragment"
+						}
 					}
 				]
 			}