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?)

root.render(reactNode)

root.unmount()

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.

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 1/12
28/2/24, 11:32 hydrateRoot – React

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

const domNode = document.getElementById('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

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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.

root.render(reactNode)

Call root.render to update a React component inside a hydrated React root

for a browser DOM element.

root.render(<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

root.render returns undefined .

Caveats

If you call root.render before the root has finished hydrating, React will
clear the existing server-rendered HTML content and switch the entire
root to client rendering.

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 3/12
28/2/24, 11:32 hydrateRoot – React

root.unmount()

Call root.unmount to destroy a rendered tree inside a React root.

root.unmount();

An app fully built with React will usually not have any calls to root.unmount .

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 root.unmount . Otherwise, the
components inside the removed root won’t clean up and free up resources
like subscriptions.

Calling root.unmount 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

root.unmount does not accept any parameters.

Returns

root.unmount returns undefined .

Caveats

Calling root.unmount will unmount all the components in the tree and
“detach” React from the root DOM node.

Once you call root.unmount you cannot call root.render again on the
root. Attempting to call root.render on an unmounted root will throw a
“Cannot update an unmounted root” error.

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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( document.getElementById('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.

index.js index.html App.js Reset

1 import './styles.css';
2 import { hydrateRoot } from 'react-dom/client';
3 import App from './App.js';
4
5 hydrateRoot(
6 document.getElementById('root'),
7 <App />
8 );
9

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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.

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 6/12
28/2/24, 11:32 hydrateRoot – React

Using browser-only APIs like window.matchMedia 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="/styles.css"></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';

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 7/12
28/2/24, 11:32 hydrateRoot – React

import App from './App.js';

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} :

index.js index.html App.js Reset

export default function App() {

return (
<h1 suppressHydrationWarning={true}>
Current Date: {new Date().toLocaleDateString()}
</h1>
);
}

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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:

index.js index.html App.js 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'}

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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 root.render 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 root.render 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:

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 10/12
28/2/24, 11:32 hydrateRoot – React

index.js index.html App.js Reset

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

import './styles.css';
import App from './App.js';

const root = hydrateRoot(

document.getElementById('root'),
<App counter={0} />
);

let i = 0;
setInterval(() => {
root.render(<App counter={i} />);

It is uncommon to call root.render on a hydrated root. Usually, you’ll update

state inside one of the components instead.

PREVIOUS

createRoot

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 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

https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html 12/12