React 18: A Look at the New Root API

Anton Ioffe - November 18th 2023 - 13 minutes read

Embark on a transformative journey through the latest topography of JavaScript's landscape as React 18 introduces its Enhanced Root API—a quantum leap in the realm of rendering. This deep dive unveils the pivotal shift in how applications come to life, with a nuanced exploration of modernization strategies, groundbreaking client and server rendering patterns, efficiency-maximizing operations, and robust component resilience. Senior developers, prepare to navigate the nuanced intricacies of concurrency, embrace new APIs designed for a future-proof ecosystem, and strategically traverse deprecations and paradigmatic shifts. This article doesn't just skim the surface—it delves into the marrow of React 18's advanced architecture, equipping you with the insights and code prowess to master the next era of web development.

React 18's Enhanced Root API: A Paradigm Shift in Rendering

React 18's new Root API revolutionizes the rendering process by introducing a system that is poised to deliver enhanced performance and more predictable behavior of applications. This transformative approach moves away from the legacy ReactDOM.render method, requiring us to evaluate the core structure of our front-end applications and the manner in which components come to life on the screen. With ReactDOM.createRoot, developers gain access to an environment designed for the concurrent rendering capabilities of React, which is critical in facilitating non-blocking UI updates and enabling interactive applications to remain responsive under heavy load or complex state transitions.

The introduction of this new Root API brings with it a refined and ergonomic way of managing roots, allowing developers to create a root once and then call the render method on it without the repetition of supplying the container node. This subtle yet significant change lays the foundation for more efficient update processing and improved memory management. By streamlining the initial setup and further interactions with the rendering target, React applications can now leverage these under-the-hood optimizations to respond swiftly to user input and state changes.

Moreover, the Root API serves as a gateway to the opt-in concurrent features underpinned by the Concurrent Mode. Concurrent Mode is an advanced React feature that unlocks new potential for enhancing user experience through seamless state updates and prioritized rendering paths. By opting into Concurrent Mode with the new Root API, developers are essentially enabling their applications to take advantage of concurrent rendering, where React can prepare multiple versions of the UI simultaneously and update the DOM without blocking the main thread.

Benevolently, this concurrent ability does not force a paradigm shift abruptly; the React team designed the Root API to respect the gradual adoption principle. Developers may choose to incrementally adopt the new rendering mechanism, easing their codebase into a future-proof state rather than undergoing a disruptive overhaul. This progressive enhancement strategy underscores React's commitment to backwards compatibility, while also paving the way for leveraging the progressively built modern features like Suspense, which operates harmoniously with the concurrent rendering paradigm.

As developers work with the Root API, it is crucial to understand the implications of this major overhaul on application predictability. The preemptive nature of concurrent rendering ensures that high-priority updates are rendered swiftly, while lower-priority ones can be interrupted and resumed, enhancing the perceived performance of applications. Although the initial learning curve requires developers to rethink component lifecycle and state management, the payoff is an application that is nimble and capable of delivering a fluid user experience, making this shift a strategic imperative for maximizing application performance.

Transitioning from Legacy to Modern: Migrating to createRoot

Migrating the bootstrapping of React applications to the new createRoot method can pave the way to leveraging the latest enhancements in React 18. The transition begins with replacing the ReactDOM.render method with ReactDOM.createRoot, followed by invoking the render method on the returned root object. Here's a simple migration example:

// Before
import ReactDOM from 'react-dom';
import App from './App';

const container = document.getElementById('root');
ReactDOM.render(<App />, container);

// After
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.getElementById('root');
const root = createRoot(container);
root.render(<App />);

Remember, as you migrate to the new API, the hydrate function is now obsolete and should not be included in the render call. Web applications using server-side rendering will use the hydrateRoot function instead:

// Server-side rendering with hydration
// Before
ReactDOM.hydrate(<App />, container);

// After
const root = hydrateRoot(container, <App />);

Common pitfalls during migration include neglecting to remove the legacy hydrate method, which can lead to confusion, and attempting to use callbacks with the render method—this is no longer supported. Additionally, the removal of unmountComponentAtNode in React 18 means you need to call unmount on the root object itself when necessary:

// Unmounting a component
// Before

// After

Adopting the new createRoot method comes with key benefits such as enhanced concurrency features, better error boundaries, and the capability to interrupt rendering to prioritize more urgent updates. Migration may require refactoring some code, but the benefits include a more resilient and responsive application.

To ensure smooth migration, developers should thoroughly test their applications post-migration for any unexpected behavior due to the fundamental changes in the rendering process. Be watchful for warnings in the console related to deprecated methods and review component lifecycles, as these may necessitate adjustments to comply with the new concurrent features. Embrace the transition by rigorously verifying that each component behaves as expected with the rendering improvements and error-handling capabilities. This due diligence will be pivotal in reaping the full benefits of React's concurrent rendering potential.

Advanced Client and Server Rendering Patterns in React 18

React 18 makes significant advances in both client and server rendering patterns, one of which is the deprecation of legacy API methods in favor of new patterns that leverage the Suspense mechanism for more efficient data fetching. React's legacy renderToString and renderToStaticMarkup functions were once the mainstay for server rendering, offering basic support for Suspense. However, with new demands for interactive and dynamic content, these APIs fell short. Now, React 18 brings more robust solutions.

Comparatively, renderToPipeableStream is React 18's response to the need for a more flexible server rendering approach, which aligns with its concurrent features. In essence, this function enables streaming SSR, letting chunks of HTML be sent to the client as they're generated, which is particularly beneficial for large applications where sending the entire content at once would be inefficient and slow user interaction. Here's an example of its usage:

import { renderToPipeableStream } from 'react-dom/server';
import App from './App';

function renderApp(res) {
    let didError = false;
    const stream = renderToPipeableStream(<App/>, {
        onShellReady() {
            res.statusCode = didError ? 500 : 200;
            res.setHeader('Content-type', 'text/html');
        onShellError(err) {
            res.statusCode = 500;
        onError(error) {
            didError = true;
            console.error('Error during rendering:', error);

This example shows a server-side rendering setup that sends rendered HTML to the client as soon as the "shell" of the application is ready, improving time-to-content and interactivity.

Client-side rendering also benefits from advances in concurrent features in React 18. While the API remains familiar, its concurrent capabilities mean that rendering work can be interrupted to accommodate more urgent updates, enhancing user experience by keeping the application responsive. An important client-rendering change is the new pattern for fetching data with Suspense, which codifies the recommended data-fetching strategy in the form of using startTransition for updates that can be delayed without blocking the main thread:

import { startTransition } from 'react';

function handleSearch(query) {
    startTransition(() => {
        // Fetch data without blocking UI updates
        fetchData(query).then(data => updateState(data));

This code demonstrates how to defer state updates after data fetching to ensure that the interface remains snappy and reactive to user input, a core tenant of React 18's concurrent rendering strategy.

The deprecation of "renderToNodeStream" indicates the strategic shift away from incremental suspense streaming on the server for a more seamless integration with React's concurrent nature. Replacement of it with renderToPipeableStream reflects a methodological emphasis on performance and user experience enabled by streaming capabilities and partial hydration that React 18 encourages.

The transition to these new rendering patterns requires developers to rethink their approach to data loading and UI updates, but the expected outcome is a significant boost in application performance and user experience. As developers examine these new patterns and apply them in modern web applications, the line between server and client blurs creating a more unified and efficient rendering pipeline.

Automatic Batching and Concurrent Operations: Maximizing Efficiency

Automatic Batching in React 18 represents a significant advancement in how updates are processed. It allows React to group multiple state updates into a single re-render for enhanced performance. Previously, only updates inside React event handlers were batched, while updates in asynchronous code, such as promises or setTimeout, would trigger individual renders. Consider the following example:

function ExampleComponent() {
  const [value, setValue] = useState(0);
  const [flag, setFlag] = useState(false);

  function handleClick() {
    setValue(v => v + 1);
    // In React 17 and before, this would cause a second render
    setTimeout(() => setFlag(f => !f), 0); 

  // In React 18, both state updates will be batched into a single render, even though one is within a timeout

  return (
      <p>Value: {value}</p>
      <p>Flag: {flag.toString()}</p>
      <button onClick={handleClick}>Update</button>

The introduction of concurrency in React 18 changes how rendering occurs. With concurrent features, React can interrupt rendering to prioritize more urgent updates, leading to smoother user experiences. This is beneficial in scenarios such as typing in an input field while a list is being fetched in the background. Here's an illustration:

function SearchComponent() {
  const [inputValue, setInputValue] = useState('');
  const [searchResults, setSearchResults] = useState([]);

  function handleChange(e) {
    startTransition(() => {
      const results = performSearch(;

  return (
      <input value={inputValue} onChange={handleChange} />
      <SearchResults results={searchResults} />

In this case, startTransition is used to mark the performSearch update as lower priority, ensuring that the input field remains responsive.

One common coding error is assuming that updates will be applied synchronously, which can lead to unexpected behavior. For example:

// Incorrect assumption that state will update synchronously
function increment() {
  setValue(value + 1);
  console.log(value); // This will log the old value, not the new one

// Correct approach using useEffect to log after state updates
useEffect(() => {
}, [value]);

When evaluating the impact of these features on your codebase, it is important to ask: Are there areas in your application that would benefit from automatic batching? How can you leverage concurrent operations to improve your user experience? Consider testing these features thoroughly and reviewing the behavior of your components, especially those relying heavily on asynchronous updates.

Automatic batching and concurrent operations are indicative of React's commitment to performance and user experience. By understanding and properly utilizing these features, developers can write more efficient and responsive applications.

Strict Mode Enhancements: Forging Robust React Components

React 18 strengthens its arsenal for creating robust applications by enhancing the Strict Mode — a development tool aimed at catching potential problems in the app before they manifest in production. It now includes additional checks specifically tailored to promote compatibility with the upcoming concurrent rendering features.

One notable enhancement is the development-only check that simulates unmounting and remounting of components on their initial mount. This might seem excessive at first, but it is invaluable in surfacing lifecycle issues that could become problematic in a concurrent rendering environment. The idea is to make components resilient to the mount-unmount-mount sequence, which reflects real-world scenarios, such as toggling between tabs that might trigger mounts and unmounts of component trees while retaining their states.

Here's how it looks in code when applying these new checks:

import { StrictMode } from 'react';
import App from './App';

const root = createRoot(document.getElementById('root'));
    <App />

In the previous versions of React, components were mounted and effects were set up like so:

// React mounts the component
// Layout effects are created
// Effect effects are created

Now, with the updated Strict Mode, React will simulate an additional cycle after mounting:

// React mounts the component
// Layout effects are created
// Effect effects are created
// Then, simulating a re-mount:
// React simulates unmounting the component
// All the layout and regular effects are cleaned up (destroyed)
// React simulates mounting the component again
// Restores the state
// Re-runs the effects as if the component was mounted for the first time

By adopting this simulation, developers are nudged to write side effects that are idempotent and do not assume they will only run once upon mounting. As a result, the components become more predictable and less prone to bugs when interacting with concurrent features.

A common coding mistake corrected by this Strict Mode enhancement involves not cleaning up side effects properly in componentWillUnmount or the cleanup function of the useEffect hook. For instance, event listeners or timers may be set up without proper cleanup, leading to memory leaks or unexpected behavior when components are unmounted:

// Mistaken way - no cleanup, potential for a memory leak
useEffect(() => {
  window.addEventListener('resize', handleResize);

// Correct way with cleanup
useEffect(() => {
  window.addEventListener('resize', handleResize);
  return () => {
    window.removeEventListener('resize', handleResize);

React’s tightened Strict Mode preemptively highlights these mistakes, ensuring that our components are bulletproofed against similar issues in concurrent rendering contexts. This presumes a significant shift in the way we perceive component lifecycle and side effects, prompting the question: Are our current components structured to thrive in a concurrent environment, or could they falter under the rigor of these new development practices?

Embracing React 18 APIs for Library Authors

With the advent of React 18, library authors are presented with novel APIs that enable them to design libraries for concurrent features. One such API is useSyncExternalStore, a hook tailored for libraries interacting with external state sources, ensuring that they stay concurrent-ready. This hook is crucial for fostering compatibility with React's new concurrent rendering features and seamless state management.

import { useSyncExternalStore } from 'react';

function useSelector(selector) {
    const store = externalStateStore; // Assume externalStateStore is your external state management system

    const getSnapshot = () => selector(store.getState());
    const subscribe = (callback) => store.subscribe(callback);

    const state = useSyncExternalStore(subscribe, getSnapshot);

    return state;


  • Seamlessly integrates React components with external state changes, even in a concurrent rendering environment.
  • Encourages clean, modular code by abstracting state synchronization.


  • Necessitates re architecting libraries based on asynchronous patterns for concurrent compatibility.
  • Potentially increases computational overhead if subscriptions are not efficiently managed, impacting performance.

For further enhancement, library developers are expected to incorporate best practices such as segregating non-critical updates from essential ones using the concurrency features of React 18. An understanding of how to handle side-effects and transitions is imperative, as shown in the following example where startTransition is leveraged within a library's data-fetching hook to prioritize UI responsiveness:

import { useState, useEffect, startTransition } from 'react';

function useLibraryDataFetcher(libraryOptions) {
    const [data, setData] = useState(null);

    useEffect(() => {
        // Assume fetchData is provided by the library to retrieve data based on given options
        startTransition(() => {
    }, [libraryOptions]);

    return data;


  • Preserves UI responsiveness by marking non-urgent state updates, thus allowing interactions to feel snappier.
  • Distinguishes between logic for immediate UI updates and asynchronous operations, resulting in more predictable rendering.


  • Introduces complexity, requiring developers to thoughtfully categorize updates as urgent or not.
  • Shifts the developer mindset towards a more nuanced understanding of state updates and effects.

The adoption of these APIs is imperative for library authors who aspire to capitalize on React 18's advanced features, necessitating a concerted push towards concurrency-oriented design. By incorporating such practices, libraries not only enhance performance and user experience but also secure their longevity amidst future React updates.

In embracing the concurrent capabilities introduced in React 18, library authors must carefully consider the implications for their design patterns and update strategies. It is prudent for maintainers to provide comprehensive documentation and clear examples that illustrate the usage of these new APIs, reducing barriers for developers integrating their libraries. Proactivity in adjusting to the ever-evolving React ecosystem will be pivotal, ensuring that libraries remain synchronously capable and forward-compatible within the dynamic landscape of web development.

Paving the Way Forward While Letting Go: Deprecations and Breaking Changes

React 18 represents a pivotal shift in front-end development, necessitating a reevaluation of both tooling and coding practices. With Internet Explorer now in the rearview, React 18 forges ahead, leveraging modern browser features like microtasks—an essential ingredient in its concurrent rendering strategy. The explicit incompatibility with Internet Explorer underscores a broader industry trend towards modern, compliant web standards, and cutting-edge features.

One substantial upgrade in React 18 is the stricter hydration error checks during the rehydration process. Historically, disparities between the server-side rendered markup and the initial client render could slip through undetected. React 18 challenges this leniency by issuing explicit warnings when it encounters discrepancies, compelling developers to rectify mismatches:

// Server-rendered markup
<div id='root'>Server Content</div>

// Client hydration with mismatched content
// React 18 will issue a warning for the mismatch
const root = ReactDOM.hydrateRoot(document.getElementById('root'), <App clientContent="Client Content" />);

Correct usage to match server and client content, thereby avoiding hydration errors, could look like this:

// Ensure the initial content matches across server and client
const root = ReactDOM.hydrateRoot(document.getElementById('root'), <App initialContent="Server Content" />);

The deprecation of APIs such as ReactDOM.render, ReactDOM.hydrate, and others signals a push toward embracing new mechanisms for tree management and state updates. Developers are prompted to migrate from the deprecated APIs to the new patterns and systems designed to interlace with React 18’s architecture. For instance, hydrateRoot is introduced for hydration:

import { hydrateRoot } from 'react-dom/client';

// Correct hydration method in React 18
const root = hydrateRoot(document.getElementById('root'), <App />);

When updating existing codebases, developers must adhere to these new norms, moving away from legacy practices to a more modular, performant, and maintainable approach.

Incorrectly clinging to deprecated APIs leads to common pitfalls, such as missing out on performance optimizations and the new error detection mechanisms. Developers should adopt the current conventions, embracing the new hydration method, and ensure proper unmounting routines that consider the updated syntax:

import { createRoot } from 'react-dom/client';

// New unmounting syntax
const root = createRoot(document.getElementById('root'));
// ...later when you need to unmount

Developers must critically evaluate their existing testing frameworks, ensuring they align with the demands of React 18, particularly the new hydration and unmounting mechanisms. The examination of codebases for compatibility with these React 18 changes is as crucial as understanding the need for modular and forward-thinking development practices when embracing these transformations.


In this article, we explore React 18's Enhanced Root API, which brings significant changes to the rendering process in JavaScript web development. We discuss how the new Root API revolutionizes rendering by enabling concurrent rendering and prioritized updates. The article also covers the migration process from the legacy ReactDOM.render method to ReactDOM.createRoot, as well as the enhanced client and server rendering patterns introduced in React 18. We explore automatic batching and concurrent operations for maximizing efficiency and discuss the enhancements in Strict Mode for creating robust React components. The article concludes with a discussion on how library authors can embrace React 18 APIs and the deprecations and breaking changes introduced in this version. As a technical challenge, readers are encouraged to migrate their React applications to the new Root API and explore the benefits of concurrent rendering in their own projects.