Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom Client APIs

React hydrateRoot() function

Reference for hydrateRoot from react-dom/client: attach React to HTML rendered on the server, reuse its DOM nodes, handle mismatches and update the root.

hydrateRoot(domNode, reactNode, options?) connects React to HTML that was already produced on the server. Instead of building the DOM from scratch, React walks the existing nodes, attaches event handlers, and takes over. The page is visible and readable before any JavaScript runs, and becomes interactive as soon as hydration completes.

You use it in apps with server rendering (a framework, or your own renderToString setup). The component tree you pass must produce the same markup as the server did; otherwise React reports a mismatch.

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

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

Try it

The editor has no server, so the examples write the "server HTML" into the container first.

Hydrating matching HTML
A mismatch is reported and repaired

Syntax

JSX
const root = hydrateRoot(domNode, reactNode, options?)
Parameter Description
domNode The element that contains the server-rendered HTML.
reactNode The React node used to render that HTML, normally <App />.
options Optional: identifierPrefix, onUncaughtError, onCaughtError, onRecoverableError. See createRoot options.

Returns a root with render(reactNode) and unmount(), the same as createRoot. Calling root.render later updates the tree; you rarely need it because state does the updating.

Errors and edge cases

  • If the HTML does not match, React logs a recoverable error and, for most mismatches, discards the mismatched part and renders it on the client (see hydration mismatch errors).
  • Throws Target container is not a DOM element. for a missing container.

Usage notes

  • Hydration does not repair every difference. A text or structure mismatch makes React throw away the server HTML up to the nearest Suspense boundary (or the whole root) and render on the client, as the second example shows. Attribute differences are only warned about in development and may be left in place. Always treat a mismatch as a bug.
  • Event handlers are attached during hydration. Clicks before that are dropped, or replayed once the relevant part has hydrated, because React hydrates in chunks and prioritizes the part the user interacts with.
  • Suspense boundaries let parts of the page hydrate independently, so one slow part does not block the rest.
  • Use the same identifierPrefix on the server and the client so useId values match.
  • Do not read window, Date.now() or Math.random() during render. They produce different output on server and client. Use useEffect, or useSyncExternalStore with a server snapshot.
  • Hydrate after the container's HTML is in place. If the container is empty, use createRoot instead.
  • The container should contain the server markup exactly: whitespace, comments or browser extensions that rewrite the HTML can cause mismatches.
  • Hydrate once. Use root.render() for updates from outside.
  • hydrate from react-dom was removed in React 19; hydrateRoot is the only API.