Skip to content
Tutorials Center
My learning

Topics

Lesson 70 of 132 ยท Advanced Patterns

The ReactDOM API Tour

A tour of react-dom in React 19: createRoot, hydrateRoot, unmount, createPortal, flushSync, resource hints, react-dom/server, and the removed legacy APIs render, hydrate and findDOMNode.

The react package knows nothing about browsers. It holds components, hooks and elements, the parts that are the same on the web, in React Native and when rendering to a string. Everything that touches the DOM lives in a second package: react-dom. Almost every project imports one function from it (createRoot) and then forgets it exists, until a bug sends them to the docs.

This lesson is a tour of what react-dom exports in React 19: how a React tree is attached to a page, how to render outside the normal parent, how to force a synchronous update, how to hint the browser about resources, and what react-dom/server does. It also lists the older APIs that were removed in React 19 (render, hydrate, unmountComponentAtNode, findDOMNode), because you will meet them in older code.

The package map

Import from What it provides
react-dom/client createRoot, hydrateRoot: attach React to a DOM node in the browser
react-dom createPortal, flushSync, resource hints (preload, preinit, preconnect, prefetchDNS), useFormStatus
react-dom/server Render to strings or streams on the server: renderToString, renderToPipeableStream, renderToReadableStream, renderToStaticMarkup
react-dom/static Prerender to static HTML: prerender, prerenderToNodeStream

createRoot

createRoot(domNode) creates a root: React's connection between a DOM container and a tree of components. You call it once, then call root.render(<App />). Later calls to render on the same root update the tree (React diffs it) instead of replacing it.

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

const root = createRoot(document.getElementById('root'));
root.render(<App />);
// later:
root.render(<App theme="dark" />); // updates, keeps state where it can
root.unmount();                    // removes the tree and runs all cleanups

Roots are cheap, and a page can have several. That is how you add React to a mostly server-rendered site: one root per widget (a search box, a cart badge), each with its own state and no shared tree. Shared state between roots needs something outside React, such as the external store pattern.

Two roots on one page, and unmount

Click both counters, then unmount B: A keeps its count because the two trees never knew about each other. Two important createRoot options: onCaughtError and onUncaughtError (React 19) let you log errors that error boundaries caught or that escaped them, which is where you connect an error-reporting service.

hydrateRoot

When the server already produced the HTML (see SSR and hydration), you do not want to throw it away and re-render. hydrateRoot(domNode, <App />) adopts the existing markup: it attaches event handlers and checks that what React would render matches what is already there. If the two differ, React reports a hydration mismatch.

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

hydrateRoot(document.getElementById('root'), <App />);

hydrateRoot returns a root with render and unmount too. Use createRoot for client-only apps and hydrateRoot only when the container already holds server output.

The removed legacy APIs

Before React 18 there was one way to start an app, and React 19 deleted it. You will see these in old tutorials and codebases.

Legacy API (removed in 19) Replacement
ReactDOM.render(<App />, node) createRoot(node).render(<App />)
ReactDOM.hydrate(<App />, node) hydrateRoot(node, <App />)
ReactDOM.unmountComponentAtNode(node) root.unmount()
ReactDOM.findDOMNode(instance) A ref on the DOM element
ReactDOM.unstable_batchedUpdates Nothing: updates are batched automatically since React 18
String refs, legacy context, react-test-renderer/shallow Callback refs or createRef, createContext, Testing Library

Why findDOMNode was removed. It let a parent reach into a child's DOM, breaking encapsulation, and it prevented React from changing how components render. The replacement is explicit: put a ref on the element you need (see refs). Why render was removed. The old entry point could not support concurrent features, because it rendered synchronously; the root created by createRoot can interrupt and resume rendering, which transitions and Suspense depend on.

A migration is mostly mechanical:

JSX
// before (React 17 and older)
import ReactDOM from 'react-dom';
ReactDOM.render(<App />, document.getElementById('root'));

// after (React 18 and 19)
import { createRoot } from 'react-dom/client';
createRoot(document.getElementById('root')).render(<App />);

createPortal

createPortal(children, domNode) renders children into a different DOM node while keeping them in the same place in the React tree. Events and context still flow through the React parent. It is how modals, tooltips and toasts escape overflow: hidden and z-index traps. The Portals lesson covers the patterns in depth; here is the API in a few lines:

JSX
import { createPortal } from 'react-dom';

function Tooltip({ children }) {
  return createPortal(<div className="tooltip">{children}</div>, document.body);
}

flushSync

React batches state updates: several setState calls in one event produce a single render, and the DOM is updated after your handler finishes. Usually that is what you want. Occasionally you must read the DOM right after a state change, for example to scroll to an item you just added. flushSync forces React to apply the updates inside the callback synchronously.

flushSync: reading the DOM straight after an update

The normal button reports one row fewer than the list will have, because the DOM has not been updated yet when the line after setItems runs. With flushSync the DOM is current. Use it sparingly: it opts out of batching, can hurt performance and cannot run while React is already rendering. Prefer useEffect, useLayoutEffect or a ref callback when they can do the job.

Resource hints

React 19 added functions that tell the browser about resources you will need soon, from any component, without touching <head> by hand. React de-duplicates them and emits the right tags, including during server rendering.

JSX
import { prefetchDNS, preconnect, preload, preinit } from 'react-dom';

function Page() {
  prefetchDNS('https://api.example.com');              // resolve the name early
  preconnect('https://cdn.example.com');               // open the connection early
  preload('/fonts/body.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
  preinit('/charts.js', { as: 'script' });             // fetch and run the script
  return <main>...</main>;
}

They are performance hints: the page works without them, and they only help when you call them early. See React SEO and Web Vitals for how this connects to loading speed.

react-dom/server

On the server there is no DOM, so react-dom/server renders a tree to text:

  • renderToString(<App />) returns a full HTML string (no Suspense streaming; kept for compatibility).
  • renderToPipeableStream (Node) and renderToReadableStream (Web streams) stream HTML as Suspense boundaries resolve. Use these for real servers.
  • renderToStaticMarkup(<App />) renders HTML without the extra attributes React uses for hydration, so it is only for static output such as emails.

The browser build of React also contains these functions, which makes them runnable in the editor:

renderToStaticMarkup and renderToString in the browser

Both strings contain &lt;World&gt;: React escapes text, which is part of its protection against injection. The onClick is missing from both, because handlers are attached later, when the browser calls hydrateRoot.

Other exports you may meet

  • useFormStatus (from react-dom) reads the pending state of the parent <form>; see useFormStatus and Optimistic UI.
  • version is the installed React DOM version string.
  • react-dom/test-utils is gone: use act from react and Testing Library.
  • react-dom/profiling is a build with profiling hooks for production measurements.

Common mistakes

  • Calling createRoot twice on the same container. React warns; keep the root in a variable and call root.render for updates.
  • Mixing react-dom and react-dom/client imports for createRoot. It lives only in react-dom/client.
  • Using hydrateRoot on an empty container, or createRoot on server-rendered markup. The first loses the DOM errors you want to see; the second throws the server HTML away and flashes.
  • Overusing flushSync. If you need it often, the design probably wants an effect or a different data flow.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which call is the React 18 and 19 replacement for ReactDOM.render(<App />, node)?

    createRoot from react-dom/client creates a root, and root.render renders into it. The legacy render function was removed in React 19.
  2. 2. When should you use hydrateRoot instead of createRoot?

    hydrateRoot adopts existing server markup and attaches event handlers. createRoot is for containers that React fills itself.
  3. 3. What replaced findDOMNode for reaching a child's DOM element?

    Refs make the access explicit and keep components encapsulated, so findDOMNode was removed.
  4. 4. What does flushSync(() => setState(x)) do?

    flushSync forces React to flush the callback's updates immediately. It is an escape hatch for the rare case of needing the updated DOM right away.
  5. 5. Why is an onClick missing from renderToString output?

    HTML cannot carry JavaScript functions. React attaches the handlers during hydration in the browser.

Summary

  • react-dom/client has createRoot (client-only) and hydrateRoot (adopt server HTML); both return a root with render and unmount.
  • A page may have several roots, each with independent state.
  • render, hydrate, unmountComponentAtNode and findDOMNode were removed in React 19.
  • createPortal renders into another DOM node; flushSync applies updates synchronously, and both should be used sparingly.
  • preload, preinit, preconnect and prefetchDNS are resource hints; react-dom/server renders to strings or streams.

Next: Client-Side Routing