What is hydration in React?

What is hydration in React? The server sends a page as HTML. React then runs in the browser, connects to that HTML, and makes it interactive. The page can appear before JavaScript finishes loading; hydration makes its buttons and other controls work.

What is hydration in React, step by step

For React hydration, SSR happens first. Then the browser takes over:

The server renders your React components to HTML.
The browser displays the HTML. You can see the content, but React event handlers are not attached yet.
The JavaScript loads, and React renders the same component tree in the browser.
React matches that tree to the HTML already on the page and attaches event handlers.
The page is interactive. Later updates work as they would in any React app.

For step 4 to work, the first browser render must match the server HTML. See the hydrateRoot reference.

React hydration explained in code

Frameworks call hydrateRoot for you. If you manage server rendering yourself, the browser entry can look like this:

src/entry.client.tsx

import { hydrateRoot } from "react-dom/client";
import { App } from "./App";
 
// The server already rendered <App /> into #root.
hydrateRoot(document.getElementById("root")!, <App />, {
  // Called when React recovers from an error, including a hydration mismatch.
  onRecoverableError(error, errorInfo) {
    console.error(error, errorInfo.componentStack);
  },
});

The hydrateRoot React API receives the existing DOM node and the React tree that produced it. You can also pass options such as onRecoverableError to log problems. If you set identifierPrefix for useId, use the same prefix on the server and in the browser. Older examples call it ReactDOM.hydrateRoot; import it from react-dom/client instead.

hydrateRoot vs createRoot

	`hydrateRoot`	`createRoot`
Starts from	HTML the server rendered	An empty DOM node
First render	Adopts existing DOM nodes	Creates every DOM node
Needs	The same output on server and client	Nothing from the server
When the output differs	A hydration error	Not applicable

Use createRoot when the server did not render the React tree. Use hydrateRoot when it did. hydration-proof marks a page mounted with createRoot as HP9003 for information: there is no server-rendered React tree to compare.

Hydration mismatch: meaning and consequences

A hydration mismatch means the first browser render does not match the server HTML. The difference might be text, an attribute, or an element. Fix the difference in the component rather than hiding the warning.

The result depends on your React version and whether you are running a development or production build:

Text or structure differs in React 19: React renders the affected tree again in the browser. If there is no containing Suspense boundary, it may render the whole root again. Development shows a diff; production may show error #418.
An attribute differs in React 19: React may leave the server attribute in place. Development warns, but production may not report it.
React 18: Development shows hydration warnings. Production can show minified errors #418, #423, or #425.

See the React hydration error guide for causes and fixes, or look up a specific message in errors.

What is hydration in web development?

In web development more broadly, hydration means making server-rendered HTML interactive in the browser. With client-only rendering, the browser builds the page from JavaScript instead of taking over an existing page.

Server HTML lets people and crawlers see content before the client app is ready. The tradeoff is that server and browser output must agree. Astro can hydrate individual React islands according to their client:* directives.

What is hydration in Next.js?

Next.js handles hydration for you. The router determines which components run in the browser:

Pages Router: the whole page is a client component tree. It is rendered on the server and hydrated in the browser.
App Router: Server Components render only on the server. Client Components, the files marked "use client", are also prerendered to HTML on the server and then hydrated. "use client" does not mean "client only".

A Client Component can still render on the server. If it reads window, localStorage, or the current time during render, its first browser output may differ. See Next.js hydration errors.

npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test

The quick start walks through the first report.

What is hydration in React?