· By John Kavanagh

What Changes When a Legacy React App Switches to createRoot

Photograph of hands holding a yellow tape measure across a workshop bench.
Image by Sherman Yang, licensed from Unsplash.

Upgrade React, run the tests, and everything still works. Change the two lines which mount the application, and a little positioning widget starts measuring the previous screen.

React 18's automatic batching makes that sequence possible. Installing the new dependency and adopting its new root API are separate steps, with a useful opportunity to check behaviour between them. I've put together a small quote editor to show the difference without dragging an entire application into the experiment.

The editor changes an amount and an "armed" flag together. An imperative helper measures the amount box and places a marker at its right edge. The amount can be correct whilst the marker is wrong, which makes this a more useful upgrade test than checking a counter alone.


Keep the Old Root as a Comparison

The React 18 upgrade guide explains that an application still mounted with ReactDOM.render retains the earlier behaviour. Adopting createRoot enables the new root behaviour:

import { createRoot } from 'react-dom/client';
import { QuoteEditor } from './app.jsx';

createRoot(document.getElementById('root')).render(<QuoteEditor />);

My comparison uses three builds: React and React DOM 17.0.2 with the legacy root, the matching 18.0.0 pair with that same root, and 18.0.0 with createRoot. The component and event handlers stay identical. Only the dependency pair and mounting entry change.

That middle build earns its place. Comparing only React 17 with a fully migrated React 18 application would change two things at once. Here, we can see which behaviour survives the dependency update and which changes when the root changes.


Count Committed Changes

The handler uses functional updates because both values depend on their previous values:

function update() {
  setAmount(value => value + 10);
  setArmed(value => !value);
}

I run it from a React click handler, a resolved promise callback, and a native listener installed with addEventListener. A layout effect records the amount, flag, and rendered text after each commit. Logging from the component function would count executions, which is a different question.

With the initial mount excluded, the React click produces one commit in all three builds. The promise and native listener each produce two commits in both legacy‑root builds: first the new amount, then the changed flag. With createRoot, those callbacks produce one commit containing both changes.

These are production builds without Strict Mode. That keeps development checks out of this particular comparison; it is not a recommendation to remove them from an application. Nor do these counts establish how much faster a real screen will feel. This example contains very little work to begin with.


The Successful Update Hides the Failed Read

The broken helper runs immediately after update(). It reads boxRef.current.getBoundingClientRect().width and moves the marker to that position.

I've made the box width deliberately uninteresting: an amount of £100 gives a width of 100 pixels, and £110 gives 110 pixels. No font measurement, animation, or network response can muddy the result.

After a promise callback, the legacy builds measure 110 pixels. The modern root measures 100 pixels at that same point, then commits the new amount. The screen finishes showing £110 with a marker ten pixels short of its edge. Checking the final text alone would pass the broken implementation.

There is a useful warning in the React‑event control too. Its immediate read is already stale with the old roots, because those updates were already batched. The helper's apparent reliability depended on where somebody called it. Moving it to another event source could have exposed the assumption before this upgrade.


Measure the Committed Element

For the marker, I can let React finish updating the DOM before measuring it. With the comparison's recording code removed, the repair is small:

useLayoutEffect(() => {
  placeMarker();
});

The helper now runs after each commit and reads the current element through boxRef.current. In this small example I deliberately measure on every commit. A larger component should identify which changes require measurement, whilst still handling replacement of the element itself.

This is layout work, so I want it done before the browser paints. The Hooks reference describes that timing. Keep the work short: measuring and moving a small marker is a rather different proposition from recalculating a whole document in a layout effect.

The repaired marker finishes at 110 pixels for every event source in the comparison. My test reads the actual box width independently and compares it with the marker position, rather than trusting the helper's own log.

I also replace the amount element by changing its key. As I covered in my article about React keys, identity affects whether React preserves an instance. Caching the first DOM node leaves the helper measuring a detached element after that replacement. Reading the current ref fixes this separate mistake; my useRef guide covers the distinction between the ref object and the value it holds.


When the Caller Cannot Wait

The comparison includes a fictional host which asks the editor to update, then immediately captures the amount and width before its callback returns. That is a stricter requirement than placing a marker before paint.

A layout effect does not make the modern root satisfy that immediate capture. For this specific control, I use an explicit synchronous flush:

flushSync(update);
placeMarker();

The host then captures £110 and 110 pixels. Its uncorrected capture sees £100, even though the eventual screen shows £110. Those two observations give the escape hatch a reason to exist. I would want an equally concrete integration requirement before keeping it in application code. The ordinary marker already has a working repair without forcing this flush.


Keep the Small Controls

Two separate clicks must still apply two changes. Two functional amount updates within one click must add £20. An update returning the existing amount must leave the DOM unchanged. My comparison checks those cases alongside the early read, the repaired measurement, the synchronous host, and the replaced element.

My root‑batching comparison contains the matched handlers and browser checks. When applying the same approach to an application, keep the awkward imperative integration in the test. A root migration can preserve every final state value and still break the code which reads the DOM a moment too soon.

Postscript

December 2024: React 19 has removed ReactDOM.render. The legacy‑root builds above are useful comparisons for this migration, but they are no longer an option when upgrading to React 19. React 18.3 adds warnings which can help identify old API use before that step.

November 2026: I've checked the comparison again with the original React 17.0.2 and 18.0.0 pairs, plus a separate React 19.3.1 modern‑root build. My download uses a newly locked Node 22 toolchain; it does not reproduce an old project's complete dependency tree. The current flushSync guidance still treats it as an uncommon integration tool, with costs and possible effects on other pending work. I'd keep the measurement tied to the commit unless the caller demonstrably needs that immediate snapshot.

Downloadable Resource

  • React Root Batching Comparison

    Replay matched React root updates, expose premature DOM measurements, and test layout‑effect repairs, synchronous host snapshots, and replaced elements.

    Download ZIP

Want to find out more?

If you need senior hands‑on support with a complex React or Next.js platform, migration, performance issue, or technical SEO problem, send me the context and I'll tell you where I can help.