· By John Kavanagh

What React 19 Changes for Shared Custom Elements

Photograph of stacked cardboard boxes on tall warehouse shelves.
Image by CHUTTERSNAP, licensed from Unsplash.

An object which arrives at a component as [object Object] has lost quite a lot of its usefulness. The brackets have survived. The configuration has not.

That is the first failure in my custom‑element comparison. A fictional stock control accepts a threshold configuration, displays a labelled number input, and emits an event when someone changes it. I use the same element in a plain browser page and in React 18.3.1 and 19.0.0, so the host has to meet an interface which exists independently of React.

React 19 improves that integration considerably. It also leaves a few decisions with whoever owns the element and its loading order. I'd check those before deleting a wrapper which has been quietly doing useful work.


Give the Element a Small Public Interface

My stock-threshold element accepts a string label attribute and a config property containing { threshold: 0 }. It exposes an enabled property and emits a case‑sensitive StockChange event with the new numeric threshold in detail.

The object property has a getter and setter on the element's prototype. The setter validates the number and updates an existing native input. Labels are assigned with textContent, so a label such as <Stock & safety> remains text. There is no reason for a stock label to become a small HTML interpreter.

A plain consumer assigns the property directly:

const element = document.createElement('stock-threshold');
element.setAttribute('label', '<Stock & safety>');
element.config = { threshold: 0 };
element.addEventListener('StockChange', event => {
  console.log(event.detail.threshold);
});
document.getElementById('root').append(element);

That consumer gives me a useful reference. If it cannot configure or operate the element, changing React versions is unlikely to be the first repair I need.


Compare the Actual Property

The direct React consumer expresses the same values as props:

<stock-threshold
  label="<Stock & safety>"
  config={{ threshold: 0 }}
  onStockChange={event => console.log(event.detail.threshold)}
/>

With the element registered before rendering, React 18.3.1 produces a config="[object Object]" attribute. The element's property retains its default threshold of five. React 19.0.0 assigns the object to the existing property, and the input starts at zero.

The React 19 release notes describe the distinction: client rendering assigns a matching instance property when one exists, otherwise it falls back to an attribute. That makes the element's defined surface significant. An arbitrary name in JSX does not establish a property on the browser object.

This is related to my earlier article about unknown DOM props, but the intention differs. Here I am deliberately integrating with a custom element's public property, rather than accidentally forwarding a component's private prop onto ordinary HTML.


Check Events Beyond the Spelling in JSX

Pressing Enter on the native increase button changes the threshold. The element dispatches its event from inside its shadow root:

new CustomEvent('StockChange', {
  detail: { threshold: value, source: 'keyboard-or-pointer' },
  bubbles: true,
  composed: true,
});

The event bubbles and is composed so this particular event can reach listeners outside the shadow boundary. My test observes its payload at the document as well as in the consumer. The outer listener sees the custom element as its target; the composed path identifies the original button.

React 19's onStockChange listener receives it. The direct React 18 consumer does not. A native listener installed by my adapter works in both versions. Changing the listener name to lowercase deliberately breaks the case‑sensitive match, even though the element still updates its own input.

Again, the final number alone would miss half the integration. The host needs the notification, not just a control which looks busy.


Registration Order Can Change the Result

Next I render before registering the element. At that point the browser has an ordinary, undefined custom‑element instance. The config property is absent, so even React 19 takes the attribute route. Registering the definition later upgrades the element, but it does not reconstruct the object from [object Object].

The plain consumer has a different problem to handle. Its direct property assignment creates an own property before upgrade. My element's constructor captures that value, deletes the own property, and assigns it again through the real setter. Otherwise, the old property can hide the setter on the prototype. The test checks both the preserved zero and the absence of that shadowing own property.

For the React adapter, I wait for the definition and then assign the configuration explicitly:

customElements.whenDefined('stock-threshold').then(() => {
  if (disposed) return;
  element.config = initialConfig;
  element.enabled = true;
});

The surrounding effect installs the native event listener and removes it on cleanup. Cleanup also sets disposed, preventing a delayed definition from configuring an element whose consumer has already unmounted. Repeated mounts are part of the test: dispatching an event on a retained old element must not notify the current consumer.

This small adapter uses a fixed initial configuration. A wrapper accepting changing configuration or callbacks also needs to apply those changes deliberately; waiting for registration once does not solve prop synchronisation in general.


Server HTML is Another Boundary

React 19's server output keeps the string label, numeric zero, and empty string. It emits a true boolean as an empty attribute, and omits both the false boolean and the object configuration. My test inspects the literal server bytes separately from the browser DOM.

Omitting an object is preferable to pretending its string representation is usable configuration. It still means the browser cannot recover the object from that HTML alone.

In this fixture, hydrating the direct consumer leaves the element's default threshold in place, even when registration happens first. No recoverable hydration error is reported. A quiet console is therefore insufficient evidence that the control received its configuration.

The hydrated adapter applies the object after definition and sets the false enabled property explicitly. The resulting input is correctly configured and disabled. I assert those properties and the native input's state, rather than treating the absence of an HTML attribute as proof of a JavaScript value.


Keep the Wrapper Where It Earns Its Place

My custom‑element comparison includes the plain consumer, both React versions, raw server output, and the adapter. It tests early and late registration, keyboard activation, label association, event payloads, wrong‑case listeners, and cleanup.

The element deliberately uses native controls inside its shadow root. It is not a form‑associated custom element and does not automatically contribute its configuration to form submission. Sharing a tag name across hosts does not remove the need to specify those behaviours.

As in my article about older React component APIs, I'd decide what to remove from the behaviour it preserves. React 19 makes the registered client‑rendered case simpler. Loading order, hydration, and an existing host's event expectations can still justify a very small adapter.

Postscript

November 2026: My comparison now includes React 19.3.1 alongside the original 18.3.1 and 19.0.0 pairs, using a newly locked Node 22 toolchain. The late‑registration and hydration cases still need the explicit configuration step in this fixture. I've also covered the wider distinction between server HTML and the first client render in my hydration debugging article. The download records the actual browser versions tested; its current tooling is not a reconstruction of a February 2025 project environment.

Downloadable Resource

  • React Custom Element Version Comparison

    Compare properties, attributes, and custom events across React versions and a plain host. Test late definition, raw server HTML, hydration, and a small adapter.

    Download ZIP

Untangling a delivery problem?

Send the symptoms, constraints, and affected routes. I'll help identify whether the issue sits in the application, platform, content model, deployment path, or search surface.