28/2/24, 11:32 hydrateRoot – React
API REFERENCE CLIENT APIS
hydrateRoot
hydrateRoot lets you display React components inside a browser
DOM node whose HTML content was previously generated by
react-dom/server .
const root = hydrateRoot(domNode, reactNode, options?)
Reference
hydrateRoot(domNode, reactNode, options?)
[Link](reactNode)
[Link]()
Usage
Hydrating server-rendered HTML
Hydrating an entire document
Suppressing unavoidable hydration mismatch errors
Handling different client and server content
Updating a hydrated root component
Reference
hydrateRoot(domNode, reactNode, options?)
Call hydrateRoot to “attach” React to existing HTML that was already
rendered by React in a server environment.
[Link] 1/12
28/2/24, 11:32 hydrateRoot – React
import { hydrateRoot } from 'react-dom/client';
const domNode = [Link]('root');
const root = hydrateRoot(domNode, reactNode);
React will attach to the HTML that exists inside the domNode , and take over
managing the DOM inside it. An app fully built with React will usually only
have one hydrateRoot call with its root component.
See more examples below.
Parameters
domNode : A DOM element that was rendered as the root element on the
server.
reactNode : The “React node” used to render the existing HTML. This will
usually be a piece of JSX like <App /> which was rendered with a
ReactDOM Server method such as renderToPipeableStream(<App />) .
optional options : An object with options for this React root.
optional onRecoverableError : Callback called when React
automatically recovers from errors.
optional identifierPrefix : A string prefix React uses for IDs
generated by useId . Useful to avoid conflicts when using multiple
roots on the same page. Must be the same prefix as used on the server.
Returns
hydrateRoot returns an object with two methods: render and unmount .
Caveats
hydrateRoot() expects the rendered content to be identical with the
server-rendered content. You should treat mismatches as bugs and fix
them.
In development mode, React warns about mismatches during hydration.
There are no guarantees that attribute differences will be patched up in
[Link] 2/12
28/2/24, 11:32 hydrateRoot – React
case of mismatches. This is important for performance reasons because in
most apps, mismatches are rare, and so validating all markup would be
prohibitively expensive.
You’ll likely have only one hydrateRoot call in your app. If you use a
framework, it might do this call for you.
If your app is client-rendered with no HTML rendered already, using
hydrateRoot() is not supported. Use createRoot() instead.
[Link](reactNode)
Call [Link] to update a React component inside a hydrated React root
for a browser DOM element.
[Link](<App />);
React will update <App /> in the hydrated root .
See more examples below.
Parameters
reactNode : A “React node” that you want to update. This will usually be a
piece of JSX like <App /> , but you can also pass a React element
constructed with createElement() , a string, a number, null , or
undefined .
Returns
[Link] returns undefined .
Caveats
If you call [Link] before the root has finished hydrating, React will
clear the existing server-rendered HTML content and switch the entire
root to client rendering.
[Link] 3/12
28/2/24, 11:32 hydrateRoot – React
[Link]()
Call [Link] to destroy a rendered tree inside a React root.
[Link]();
An app fully built with React will usually not have any calls to [Link] .
This is mostly useful if your React root’s DOM node (or any of its ancestors)
may get removed from the DOM by some other code. For example, imagine a
jQuery tab panel that removes inactive tabs from the DOM. If a tab gets
removed, everything inside it (including the React roots inside) would get
removed from the DOM as well. You need to tell React to “stop” managing
the removed root’s content by calling [Link] . Otherwise, the
components inside the removed root won’t clean up and free up resources
like subscriptions.
Calling [Link] will unmount all the components in the root and
“detach” React from the root DOM node, including removing any event
handlers or state in the tree.
Parameters
[Link] does not accept any parameters.
Returns
[Link] returns undefined .
Caveats
Calling [Link] will unmount all the components in the tree and
“detach” React from the root DOM node.
Once you call [Link] you cannot call [Link] again on the
root. Attempting to call [Link] on an unmounted root will throw a
“Cannot update an unmounted root” error.
[Link] 4/12
28/2/24, 11:32 hydrateRoot – React
Usage
Hydrating server-rendered HTML
If your app’s HTML was generated by react-dom/server , you need to
hydrate it on the client.
import { hydrateRoot } from 'react-dom/client';
hydrateRoot( [Link]('root') , <App /> );
This will hydrate the server HTML inside the browser DOM node with the
React component for your app. Usually, you will do it once at startup. If you
use a framework, it might do this behind the scenes for you.
To hydrate your app, React will “attach” your components’ logic to the initial
generated HTML from the server. Hydration turns the initial HTML snapshot
from the server into a fully interactive app that runs in the browser.
[Link] [Link] [Link] Reset
1 import './[Link]';
2 import { hydrateRoot } from 'react-dom/client';
3 import App from './[Link]';
4
5 hydrateRoot(
6 [Link]('root'),
7 <App />
8 );
9
[Link] 5/12
28/2/24, 11:32 hydrateRoot – React
You shouldn’t need to call hydrateRoot again or to call it in more places.
From this point on, React will be managing the DOM of your application. To
update the UI, your components will use state instead.
Pitfall
The React tree you pass to hydrateRoot needs to produce the same
output as it did on the server.
This is important for the user experience. The user will spend some
time looking at the server-generated HTML before your JavaScript
code loads. Server rendering creates an illusion that the app loads
faster by showing the HTML snapshot of its output. Suddenly
showing different content breaks that illusion. This is why the server
render output must match the initial render output on the client.
The most common causes leading to hydration errors include:
Extra whitespace (like newlines) around the React-generated
HTML inside the root node.
Using checks like typeof window !== 'undefined' in your
rendering logic.
[Link] 6/12
28/2/24, 11:32 hydrateRoot – React
Using browser-only APIs like [Link] in your
rendering logic.
Rendering different data on the server and the client.
React recovers from some hydration errors, but you must fix them
like other bugs. In the best case, they’ll lead to a slowdown; in the
worst case, event handlers can get attached to the wrong elements.
Hydrating an entire document
Apps fully built with React can render the entire document as JSX, including
the <html> tag:
function App() {
return (
<html>
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1
<link rel="stylesheet" href="/[Link]"></link>
<title>My app</title>
</head>
<body>
<Router />
</body>
</html>
);
}
To hydrate the entire document, pass the document global as the first
argument to hydrateRoot :
import { hydrateRoot } from 'react-dom/client';
[Link] 7/12
28/2/24, 11:32 hydrateRoot – React
import App from './[Link]';
hydrateRoot(document, <App />);
Suppressing unavoidable hydration mismatch errors
If a single element’s attribute or text content is unavoidably different
between the server and the client (for example, a timestamp), you may
silence the hydration mismatch warning.
To silence hydration warnings on an element, add
suppressHydrationWarning={true} :
[Link] [Link] [Link] Reset
export default function App() {
return (
<h1 suppressHydrationWarning={true}>
Current Date: {new Date().toLocaleDateString()}
</h1>
);
}
[Link] 8/12
28/2/24, 11:32 hydrateRoot – React
This only works one level deep, and is intended to be an escape hatch. Don’t
overuse it. Unless it’s text content, React still won’t attempt to patch it up, so
it may remain inconsistent until future updates.
Handling different client and server content
If you intentionally need to render something different on the server and the
client, you can do a two-pass rendering. Components that render something
different on the client can read a state variable like isClient , which you can
set to true in an Effect:
[Link] [Link] [Link] Reset
import { useState, useEffect } from "react";
export default function App() {
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
return (
<h1>
{isClient ? 'Is Client' : 'Is Server'}
[Link] 9/12
28/2/24, 11:32 hydrateRoot – React
This way the initial render pass will render the same content as the server,
avoiding mismatches, but an additional pass will happen synchronously right
after hydration.
Pitfall
This approach makes hydration slower because your components
have to render twice. Be mindful of the user experience on slow
connections. The JavaScript code may load significantly later than
the initial HTML render, so rendering a different UI immediately after
hydration may also feel jarring to the user.
Updating a hydrated root component
After the root has finished hydrating, you can call [Link] to update the
root React component. Unlike with createRoot , you don’t usually need to
do this because the initial content was already rendered as HTML.
If you call [Link] at some point after hydration, and the component
tree structure matches up with what was previously rendered, React will
preserve the state. Notice how you can type in the input, which means that
the updates from repeated render calls every second in this example are not
destructive:
[Link] 10/12
28/2/24, 11:32 hydrateRoot – React
[Link] [Link] [Link] Reset
import { hydrateRoot } from 'react-dom/client';
import './[Link]';
import App from './[Link]';
const root = hydrateRoot(
[Link]('root'),
<App counter={0} />
);
let i = 0;
setInterval(() => {
[Link](<App counter={i} />);
It is uncommon to call [Link] on a hydrated root. Usually, you’ll update
state inside one of the components instead.
PREVIOUS
createRoot
[Link] 11/12
28/2/24, 11:32 hydrateRoot – React
NEXT
Server APIs
How do you like these docs?
Take our survey!
©2024
Learn React API Reference
Quick Start React APIs
Installation React DOM APIs
Describing the UI
Adding Interactivity
Managing State
Escape Hatches
Community More
Code of Conduct Blog
Meet the Team React Native
Docs Contributors Privacy
Acknowledgements Terms
[Link] 12/12
