{"id":29602129,"url":"https://github.com/preactjs/preact-root-fragment","last_synced_at":"2025-07-22T16:01:47.604Z","repository":{"id":304969234,"uuid":"1020669591","full_name":"preactjs/preact-root-fragment","owner":"preactjs","description":"A standalone Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10","archived":false,"fork":false,"pushed_at":"2025-07-16T09:37:37.000Z","size":61,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-17T14:33:35.569Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/preactjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["preactjs"],"open_collective":"preact"}},"created_at":"2025-07-16T08:09:05.000Z","updated_at":"2025-07-16T17:55:17.000Z","dependencies_parsed_at":"2025-07-17T17:53:41.829Z","dependency_job_id":"84daf3b7-2f47-40ff-b3df-27625cb78073","html_url":"https://github.com/preactjs/preact-root-fragment","commit_stats":null,"previous_names":["preactjs/preact-root-fragment"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/preactjs/preact-root-fragment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fpreact-root-fragment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fpreact-root-fragment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fpreact-root-fragment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fpreact-root-fragment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/preactjs","download_url":"https://codeload.github.com/preactjs/preact-root-fragment/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fpreact-root-fragment/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265748292,"owners_count":23822082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-20T14:00:22.592Z","updated_at":"2025-07-21T15:02:01.538Z","avatar_url":"https://github.com/preactjs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/preactjs","https://opencollective.com/preact"],"categories":[],"sub_categories":[],"readme":"# `preact-root-fragment`: partial root rendering for Preact\n\nThis is a standalone Preact 10+ implementation of the deprecated `replaceNode` parameter from Preact 10.\n\nIt provides a way to render or hydrate a Preact tree using a subset of the children within the parent element passed to render():\n\n```html\n\u003cbody\u003e\n  \u003cdiv id=\"root\"\u003e ⬅ we pass this to render() as the parent DOM element...\n\n    \u003cscript src=\"/etc.js\"\u003e\u003c/script\u003e\n\n    \u003cdiv class=\"app\"\u003e ⬅ ... but we want to use this tree, not the script\n      \u003c!-- ... --\u003e\n    \u003c/div\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\n### Why do I need this?\n\nThis 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 `\u003csection\u003e` would get hydrated without clobbering the others?\n\n```html\n\u003cdiv id=\"sidebar\"\u003e\n  \u003csection id=\"widgetA\"\u003e\u003ch1\u003eWidget A\u003c/h1\u003e\u003c/section\u003e\n  \u003csection id=\"widgetB\"\u003e\u003ch1\u003eWidget B\u003c/h1\u003e\u003c/section\u003e\n  \u003csection id=\"widgetC\"\u003e\u003ch1\u003eWidget C\u003c/h1\u003e\u003c/section\u003e\n\u003c/div\u003e\n```\n\nPreact 10 provided a somewhat obscure third argument for `render` and `hydrate` called `replaceNode`, which could be used for the above case:\n\n```js\nrender(\u003cA /\u003e, sidebar, widgetA); // render into \u003cdiv id=\"sidebar\"\u003e, but only look at \u003csection id=\"widgetA\"\u003e\nrender(\u003cB /\u003e, sidebar, widgetB); // same, but only look at widgetB\nrender(\u003cC /\u003e, sidebar, widgetC); // same, but only look at widgetC\n```\n\nWhile 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.\n\nGoing forward, we're providing this functionality as a standalone library called `preact-root-fragment`.\n\n### How it works\n\n`preact-root-fragment` provides a `createRootFragment` function:\n\n```ts\ncreateRootFragment(parent: ContainerNode, children: ContainerNode | ContainerNode[]);\n```\n\nCalling 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.\n\nUsing the previous example, we can change the deprecated `replaceNode` usage out for `createRootFragment`:\n\n```js\nimport { createRootFragment } from 'preact-root-fragment';\n\nrender(\u003cA /\u003e, createRootFragment(sidebar, widgetA));\nrender(\u003cB /\u003e, createRootFragment(sidebar, widgetB));\nrender(\u003cC /\u003e, createRootFragment(sidebar, widgetC));\n```\n\nSince we're creating separate \"Persistent Fragment\" parents to pass to each `render()` call, Preact will treat each as an independent Virtual DOM tree.\n\n### Multiple Root Elements\n\nUnlike 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:\n\n```js\nimport { createRootFragment } from 'preact-root-fragment';\nimport { render } from 'preact';\n\nfunction App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eExample\u003c/h1\u003e\n      \u003cp\u003eHello world!\u003c/p\u003e\n    \u003c/\u003e\n  );\n}\n\n// Use only the last two child elements within \u003cbody\u003e:\nconst children = [].slice.call(document.body.children, -2);\n\nrender(\u003cApp /\u003e, createRootFragment(document.body, children));\n```\n\n### Preact Version Support\n\nThis library works with Preact 10 and 11.\n\n### Changelog\n\n#### 0.2.0 (2022-03-04)\n\n- fix bug where nodes were appended instead of replaced (thanks @danielweck)\n- fix `.__k` assignment (thanks @danielweck)\n- fix Preact 10.6 debug error due to missing `nodeType` (thanks @danielweck)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreactjs%2Fpreact-root-fragment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpreactjs%2Fpreact-root-fragment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreactjs%2Fpreact-root-fragment/lists"}