Hoistable SVG Defs, Take Two: Impersonating the DOM
Deduplicating SVG definitions in React by portaling them into a plain object that impersonates a DOM node, the trick behind React Aria's Collections.
Published
Deduplicating SVG definitions in React by portaling them into a plain object that impersonates a DOM node, the trick behind React Aria's Collections.
SVG has elements that don't render directly — <marker>, <linearGradient>, <clipPath> — but define something for graphics elements to reference with url(#id).
These belong in a <defs> element, and references resolve document-wide. That can lead to id-clashes, and it leaves React components with a conceptual problem. A component can't own the definitions it depends on.
I wanted what React 19 does for <head> tags, but for <defs>:
<defs> elementThe solution was:
<DefsProvider> to store a reference to a React-rendered <defs> DOM node using a ref callback into state, shared through context.<DefsPortal>, which portals them into that single <defs>.Map in state keyed by the def's id, where every portal instance registers itself in a useEffect and unregisters in its cleanup. The first instance to claim an id wins and renders the definition; the rest render null.I can imagine this summary is not very clear so I recommend just reading the first post.
I ended it with a confession. The registry pattern works, but it tracks component mount and unmount by abusing useEffect setup and cleanup.
React already knows which components are mounted in the Fiber tree, but we can't access that information 1.
So our registry shadowed a slice of that knowledge from the outside. It worked but it felt icky, against the grain.
The deduplication problem — "am I the first <defs> with this id in the whole component tree?" — is an instance of a parent component needing to know about its children.
Jay Freestone catalogued a few solutions to this problem in his blogpost Updating React parents in response to changes in children 2:
Children.toArray. This only sees direct children. Also, I find Children ugly and unidiomatic React. It's dated and the React docs recommend against using it 3.That last one me.
React Aria's collection components — listboxes, menus, tables — face the problem in a harder form.
For example, a <ListBox> needs the full ordered list of its options to implement keyboard navigation and selection, but the options are JSX, composed by the user, possibly nested in wrapper components the listbox can't see through.
So I went digging through React Aria's code, and found their solution very smart and out-of-the-box. It doesn't go against the grain of React, instead it uses React's internal mechanisms.
They render the children into a fake document 4, portaling into it with createPortal(children, fakeDocument), where fakeDocument is not a DOM node but a plain JavaScript class that implements just enough of the DOM interface (createElement, appendChild, insertBefore, removeChild) to satisfy react-dom.
Why does that even work?
When react-dom commits, it has to tell the container it's rendering into about every mount and unmount.
Usually this is the root element passed to createRoot but it can also be a portal's target element 5.
react-dom will call appendChild and removeChild on that container. That's what committing means.
So hand a portal a fake container and you get to eavesdrop on the commit phase. react-dom calls our appendChild on every mount, our removeChild on every unmount.
The bookkeeping we rebuilt with useEffect in Take One, the reconciler gives for free.
That's react-dom writing into the fake document, and those writes are exactly the information we're after. The reconciler itself now reports which components are mounted.
But that leaves the collection of children sitting outside React, in a plain JavaScript object — and whatever renders from the collection must re-render when it changes.
The data needs to flow back out.
Reading 'outside' state in a render is exactly what useSyncExternalStore is for. You give it a subscribe and a getSnapshot function, and React re-renders the subscribed component whenever the store reports a change.
Here the fake document where the defs children are written into is the store.
Which makes this a strange case of "external store".
Usually the store is, well, actually external — some state management library like Redux, or Jotai, or a browser API like matchMedia.
This one is fed by react-dom's commit phase, through the only channel it offers the outside world, the DOM interface.
What we're really subscribing to is the Fiber tree, the mount state that our registry from Take One could only shadow from the outside.
React, plugged back into its private internals.
You might worry about the performance of all this extra rendering. Every change to the collection now takes two render passes. The first renders the portal into the fake document, and a second pass renders the items into the real DOM. The React Aria team raised this downside themselves in the Collections RFC 6. But that first pass only writes to plain JavaScript objects, which are far cheaper than real DOM nodes, and in their testing it never became a problem. If it's good enough for them, it's good enough for me.
So could the same trick fix the duplicate <defs> problem? Can we just import theirs?
We can't just import React Aria's solution.
Parts of the machinery are public but the part we need, the intercepting fake Document class itself, is private 7.
Also their needs are a lot heavier. Keyboard navigation and selection need the complete ordered list before item one can render.
For Defs we need none of that, we just need a flat Map.
We'll impersonate the DOM ourselves.
The component-facing API stays the same, declare defs inside a <DefsPortal>, reference them by id.
What changes is where the portal goes. It no longer portals into the real <defs> element, but into a fake container.
This is a place off to the side of the real DOM where the definitions gather before they're added for real.
The only JSX that enters the fake container is the def declarations themselves:
function Arrow({ path }) { return ( <> {/* portaled into the fake container */} <DefsPortal id="arrow"> <marker id="arrow" /* … */ /> </DefsPortal> {/* becomes real DOM, rendered once */} <path d={path} markerEnd="url(#arrow)" /> </> );}
Before we can build the fake container, we need to know what react-dom demands of one.
This is not really documented. I checked it by giving createPortal a Proxy object that logs every property access and forwards to the real implementation, mounting and unmounting a portal, and then reading the log.
For react-dom 19, this returned the following properties being touched.
| Property | Why |
|---|---|
nodeType | isValidContainer and namespace resolution — report 11, a DocumentFragment |
addEventListener | react-dom attaches its delegated event listeners to every portal container, capture and bubble |
ownerDocument | how react-dom finds createElement |
nodeName | dev-mode container validation — reads undefined and carries on |
createElement | creating our fake <def> elements |
appendChild, removeChild | the commit calls: every mount and unmount lands here |
getRootNode | feature-detecting shadow-DOM containment; undefined falls back to ownerDocument |
documentElement | namespace lookup for the root host context |
onclick | a mobile-Safari click-delegation quirk |
_reactListening*, _reactRootContainer, __reactProps$* | react-dom's own bookkeeping, assigned as ad-hoc properties directly on the object — plain objects accept these for free |
Each <DefsPortal> portals a single placeholder into the fake container, <Def />, really just the string "def" in a type-level disguise.
On commit, react-dom calls createElement("def") on our container and appends whatever comes back. That plain DefElement object is our registry entry.
That entry has to carry the definition's id and its JSX untouched, because <Defs> will later render that exact JSX for real.
But props can't carry them. react-dom pushes every prop through its attribute pipeline, which stringifies values, so our JSX would arrive as "[object Object]".
Children are worse. react-dom would render them into the fake container, and now we're implementing half the DOM.
The one thing that skips this pipeline is the ref.
React calls the ref callback itself at commit, handing over the object createElement returned. A plain function call, everything by reference.
So the placeholder gets no props except a ref, and the ref callback hands the real props to the fake element directly.
export function DefsPortal({ id, children }) { const container = useContext(DefsContext); const ref = useCallback((node) => { node?.setProps({ id, children }); }, [id, children]); return createPortal(<Def ref={ref} />, container as unknown as Element);}
Refs attach during the commit phase, right after insertion, so the fake element has its props before any subscriber reads the registry.
And because the callback's identity changes when id or children change, updates flow through the same channel.
See the full live code on StackBlitz.
The container is the portal target and the store:
// A stable reference: a fresh [] on every call would loop useSyncExternalStoreconst EMPTY: Array<DefRecord> = [];export class DefsContainer { nodeType = 11; // DocumentFragment, per isValidContainer ownerDocument = this; // react-dom finds createElement through here childNodes = []; createElement(type) { return new DefElement(this); } appendChild(child) { this.childNodes.push(child); this.markDirty(); return child; } insertBefore(child, before) { const index = this.childNodes.indexOf(before); this.childNodes.splice(index, 0, child); this.markDirty(); return child; } removeChild(child) { const index = this.childNodes.indexOf(child); if (index >= 0) { this.childNodes.splice(index, 1); this.markDirty(); } return child; } addEventListener() {} // event delegation lands here; no-op removeEventListener() {} // --- The part React components talk to --- subscribe = (fn) => { /* Set of subscribers */ }; getSnapshot = () => { /* dedupe childNodes by id, first in document order wins, cached */ }; getServerSnapshot = () => EMPTY; // portals don't run during SSR markDirty() { this.snapshot = null; this.subscribers.forEach((fn) => fn()); }}
<Defs> stops being an empty <defs ref={...}> waiting to be portaled into.
It subscribes to the container with useSyncExternalStore and renders the deduplicated definitions itself:
export function Defs() { const container = useContext(DefsContext); const defs = useSyncExternalStore( container.subscribe, container.getSnapshot, container.getServerSnapshot, ); return ( <defs> {defs.map(({ id, children }) => ( <Fragment key={id}>{children}</Fragment> ))} </defs> );}
The whole trick in one diagram:
Compare this to Take One's registry and notice everything that's gone:
useEffect. Registration is mounting. react-dom calls appendChild when the portal mounts and removeChild when it unmounts; there's nothing left to synchronize.instanceId with useId. Ownership is document order. The snapshot dedupes by id, the first mounted instance wins, and when the winner unmounts the next definition surfaces in the recomputed snapshot automatically.The wishlist from last time still gets every check and this time without any icky feelings:
<defs> elementThe useEffect registry of Take One bent a documented API out of shape.
But the effect registry reconstructed mount state from the outside, shadowing what React already knew.
Here we bend an undocumented API into shape. The set of methods react-dom calls on a portal container is a private contract that can shift between React versions. The fake container gets told directly, by the reconciler itself, every time it commits.
It's still weird and a lot of code for what is, honestly, a minor problem. But this time it's less weird and done tastefully.
React stores an internal data structure that tracks all the current component instances that exist in the application. The core piece of this data structure is an object called a "fiber".Mark Erikson: Blogged Answers: A (Mostly) Complete Guide to React Rendering Behavior
React ARIA/Spectrum has a very neat, if a bit wild, solution. They provide a ‘collection’ component API that looks like this: [...] Their focus/state management (and more) requires knowledge of how many Item components there are, but each item might not be a direct child of a collection. Users may wish to wrap them for layout and/or styling. They perform a first-pass render to a fake ‘document’ inside a portal:Jay Freestone: Updating React parents in response to changes in children
Pitfall: Using Children is uncommon and can lead to fragile code. See common alternatives.React docs API Reference: Legacy React APIs - ChildrenA mutable element node in the fake DOM tree. It owns an immutable Collection Node which is copied on write.react-spectrum: Document.ts
React DOM docs API Reference: createPortal — ParametersdomNode: Some DOM node, such as those returned bydocument.getElementById(). The node must already exist. Passing a different DOM node during an update will cause the portal content to be recreated.
The main limitation has been about composition: in our current implementation,React Spectrum RFC: React Aria Components - Collections<Item>must be a direct child of the collection component and cannot be within a wrapper component like<MySpecialItem>. This is a minor frustration for developers who expect these components to work like any other React component. This will become more important in React Aria Components where creating a wrapper with reusable styles will be common. Rather than walking the JSX tree to collect items, the new implementation will rely on React itself to build and efficiently update collections. It works by implementing a tiny version of the DOM with just the methods React needs (e.g. createElement, appendChild, etc.). Then, it uses a React portal to render the collection into this fake DOM. React takes care of rendering all intermediary wrapper components, and leaf components like<Item>are rendered as "host" elements (similar to real DOM nodes). This gives us access to the underlying items as if they were rendered directly to the DOM, but without needing to pay this cost for large collections. We use this information to construct a Collection using the same interface as in the old implementation so all of our existing hooks work with it. Note that props passed to<MyItem>must be manually passed through to the underlying<Item>for it to work properly. In addition, this implementation has two downsides: 1. It requires two renders whenever something in the collection changes. The first causes the portal to be rendered, which updates the fake DOM. It then needs to kick off a second render pass to render the items into the real DOM. However, because the first pass is rendering into a fake DOM, it is quite fast and in testing so far hasn't been a problem. 2. Our current implementation heavily uses the React key prop to identify items in collections. However, this will not work with the new implementation because key is not passed through from the<Item>element to the implementation of the Item component. Therefore, we will need to use a different prop name such as id that is passed through. This would be a breaking change to switch to by default, but for React Aria Components this is ok since it is a new library. We will need to think through how to release this in our existing React Aria hooks and React Spectrum components separately.
@react-aria/collections on npm@react-aria/collectionsexposesCollectionBuilder,createLeafComponent,createBranchComponent,BaseCollection,useCachedChildren, and theHiddenutilities but not the fakeDocumentclass itself.