React inside a custom element, once

The gate is hand-written DOM and that was the right call for a component with one button and a badge. The trace view is not. It is a React tree built in “Making an agent’s work legible,” it renders a tool-calling loop that can fail halfway through, and rewriting it in vanilla DOM to get it into a host would be an act of self-harm.

So you wrap it. That part takes about fifteen lines. The engineering is everything after it: what the element is allowed to assume about the page it lands in, and how much React you are willing to ship into a host that already has some.

The wrapping is the easy half

React 19 closed the interoperability gap in both directions. The release post states it directly: “React 19 adds full support for custom elements and passes all tests on Custom Elements Everywhere.” Custom Elements Everywhere is a third-party interoperability suite rather than React’s own tooling, and its React results page is where the 100% figure across its sixteen tests comes from.

That fact is about the direction where a React host renders your tag, and it is worth knowing precisely because it decides how a host passes you data. On the client, React 19 assigns a prop as a property when a property of that name already exists on the element instance at construction time, and as an attribute otherwise. During server rendering, props whose values are objects, symbols, functions or false are omitted rather than serialised. If your element only defines its properties lazily, a React host will quietly send strings into an API you designed for objects.

The direction this lesson is about is the other one: a React tree living inside your element. Mounting a root into a shadow root is an unremarkable use of a documented API, and react.dev does not name it as a recipe, so treat the shape below as this course’s construction rather than an official pattern.

class AgentTraceElement extends HTMLElement {
  connectedCallback() {
    const root = this.attachShadow({ mode: 'open' })
    const mountPoint = document.createElement('div')
    root.appendChild(mountPoint)
    this._root = createRoot(mountPoint)
    this._root.render(<AgentTrace />)
  }

  disconnectedCallback() {
    this._root?.unmount() // React does not do this when the element is removed
  }
}
customElements.define('agent-trace', AgentTraceElement)

Two details in there are load-bearing. The unmount() is yours to call: removing the host element from the document does not tear down a React root, and in a host that mounts and unmounts a panel repeatedly, the leak compounds. And connectedCallback can fire more than once, because moving an element in the DOM disconnects and reconnects it. MDN’s custom elements guide documents the newer connectedMoveCallback, which fires instead of the disconnect-and-connect pair when the host uses Element.moveBefore() — so a move no longer has to cost you a full remount, if you implement it.

For styles inside that root, prefer a constructed stylesheet over a <style> per instance: MDN records adoptedStyleSheets as Baseline widely available since March 2023 (checked 2026-09-03), which parses the CSS once and shares it across every instance the host renders.

Get the singleton claim exactly right

The received wisdom is “React is not a singleton, so two copies break hooks.” React’s own documentation says the opposite of the first clause. The invalid hook call warning page states: “In general, React supports using multiple independent copies on one page (for example, if an app and a third-party widget both use it). It only breaks if require('react') resolves differently between the component and the react-dom copy it was rendered with.”

So the failure condition is narrow and specific: hooks break when a component’s react import and the react import of the react-dom that rendered it resolve to different module instances, within the same render. Two entirely separate React copies, each rendering its own tree with its own react-dom, are fine. This distinction is not pedantry: it is the difference between a debugging session that looks for a misconfigured shared dependency and one that looks for a second copy and deletes it, which will not fix anything on its own.

What the element is allowed to assume

This is the part that changes the component rather than the build. Whichever copy of React you end up on, the element is a separate tree in a separate root inside a shadow boundary, and that forecloses a set of assumptions a React developer makes without noticing.

• No host context. A separate root cannot read the host’s providers, and on a separate module instance the context objects are not even the same objects. No theme provider, no router, no query client, no auth context. Everything comes in as attributes and properties and goes out as events — the same channel the boundary lesson already forced you into.
• No assumption that you are the only root. A host may render several gates and traces on one page, so anything you attach to document or window is shared with your other instances. Scope listeners to your own root and clean them up in disconnectedCallback.
• No assumption about React’s version if you externalise. Taking the host’s React means inheriting their version, their development or production build, and their upgrade schedule. Your component now has a compatibility range it must state and test, which is a line in the graft contract, not a detail.

The default that survives contact with all three hosts is: bundle React, externalise nothing, and offer an externalised build as a documented variant for hosts that ask. The Angular host and the plain HTML page have no React to borrow, and a variant that only exists for one host in three is a variant you build when that host asks for it, with the number that justifies it in hand.

What this does not cover

Sharing a dependency between separately built and separately deployed applications is a different problem from bundling one, and it has its own failure mode with its own configuration. The Module Federation lesson takes the singleton condition named here and shows how a build configuration produces it, including how to reproduce it deliberately so it is recognisable in someone else’s repository. The lesson on orchestration covers what single-spa does that Module Federation does not, and the iframe lesson covers the option that isolates hardest and charges most.

Making the element look like it belongs is the module after that. The custom properties named in the shadow-boundary lesson become a real theming channel in the lesson on extracting the host brand, one token source is compiled per host in the lesson on token compilation, and the three-host demo is where this bundle either runs unchanged in all three or does not.