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.
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.
Syntax
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
Suspenseboundary (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.
Suspenseboundaries let parts of the page hydrate independently, so one slow part does not block the rest.- Use the same
identifierPrefixon the server and the client souseIdvalues match. - Do not read
window,Date.now()orMath.random()during render. They produce different output on server and client. UseuseEffect, oruseSyncExternalStorewith a server snapshot. - Hydrate after the container's HTML is in place. If the container is empty, use
createRootinstead. - 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. hydratefromreact-domwas removed in React 19;hydrateRootis the only API.