Server rendering and hydration

A page you can see before its JavaScript arrives

Every React page so far started empty. Its index.html held <div id="root"></div>, and nothing showed until the JavaScript had downloaded and createRoot had filled the root. On a fast laptop that takes a moment. On a slow phone it can take seconds of blank screen.

Server rendering fixes the blank screen. A server runs your components first, turns what they return into HTML, and sends that HTML in the page. Here is a tiny server in Node.js for a tea shop's product page. It runs on a server, not in your browser, so it has no result here:

import { createServer } from "node:http";
import { renderToString } from "react-dom/server";
import ProductPage from "./ProductPage.jsx";

createServer((request, response) => {
  const html = renderToString(<ProductPage />);
  response.setHeader("Content-Type", "text/html");
  response.end(`<!doctype html>
<html>
  <body>
    <div id="root">${html}</div>
    <script type="module" src="/main.js"></script>
  </body>
</html>`);
}).listen(3000);

Line 2 imports renderToString from react-dom/server, the part of React that renders to HTML instead of to a page. For every request, line 6 calls it with <ProductPage /> and gets back a string of HTML. Lines 8 to 14 send a whole page: that HTML sits inside <div id="root"> on line 11, and line 12 loads the browser's JavaScript, main.js.

The browser shows the HTML as soon as it arrives. Then main.js loads and connects React to it. This example is that page. Its index.html tab holds the HTML the server sent, and its main.jsx is the browser's JavaScript. The result is live: click Add to cart.

1import { hydrateRoot } from "react-dom/client";2import ProductPage from "./ProductPage.jsx";3 4hydrateRoot(document.getElementById("root"), <ProductPage />);

Line 1 imports hydrateRoot from react-dom/client. Line 4 gives it the root element, which already holds the server's HTML, and the same <ProductPage /> the server rendered. The count goes up when you click, and the console under the result shows Effect ran: the page is live. Open the ProductPage.jsx tab: it's an ordinary component with state on line 4 and an Effect on lines 5 to 7.

Connecting React to HTML that's already on the page is called hydration. The HTML is the dry page; the JavaScript is the water that brings it to life.

Turning components into HTML

react-dom/server runs in a browser too, which makes it easy to watch. This example renders ProductPage to HTML inside the result frame and prints the string. It doesn't hydrate anything:

1import { renderToString } from "react-dom/server";2import ProductPage from "./ProductPage.jsx";3 4const html = renderToString(<ProductPage />);5console.log(html);6document.getElementById("root").textContent = html;

Line 4 renders the component, line 5 prints the HTML to the console, and line 6 shows it as text in the result. Read it closely:

• The elements and their text are there: <h1>Green tea</h1> and the price.
• The count is 0, the starting value from useState(0) on line 4 of ProductPage.jsx. The server renders each component once, with its starting state.
• The onClick is gone. HTML can't hold a JavaScript function, so the button arrives with no handler.
• The console shows no Effect ran. Effects never run on the server: there is no page to change yet.
• <!-- --> appears twice inside the button. The button holds three pieces of text, Add to cart (, the count, and ). A browser would read them as one, so React marks where each ends, and splits them again while hydrating.

Press Edit & run, open the ProductPage.jsx tab, and change useState(0) on line 4 to useState(2). The HTML now says Add to cart (<!-- -->2<!-- -->).

renderToString returns right away, so it can't wait for data. This product page, in the ReviewsPage.jsx tab, loads its reviews with use inside a Suspense boundary, and the reviews take half a second:

1import { renderToString } from "react-dom/server";2import ReviewsPage from "./ReviewsPage.jsx";3 4console.log(renderToString(<ReviewsPage />));

In ReviewsPage.jsx, lines 3 to 5 make a promise that gives the reviews after 500 ms, and line 8 waits for it with use. Line 4 of main.jsx renders the page with renderToString, and the console shows the fallback, Loading reviews..., between <!--$!--> and <!--/$-->. That marker tells the browser to render this boundary itself; in a development build, the template after it says why.

React 19 added prerender, in react-dom/static, which waits. It runs on a server or in a build step, so this code has no result here:

import { prerender } from "react-dom/static";
import ReviewsPage from "./ReviewsPage.jsx";

const { prelude } = await prerender(<ReviewsPage />);
const html = await new Response(prelude).text();
console.log(html);

Line 4 waits until every Suspense boundary has its data, then gives back prelude, a stream of HTML, and line 5 reads it into a string. Half a second later line 6 prints <main><h1>Green tea</h1><!--$--><p>5 stars from Asha</p><!--/$--></main>: the reviews themselves, in a finished boundary, <!--$-->.

Read the table row by row: the API, what it gives you, and whether it waits for a component that suspends.

React's docs recommend the streaming APIs for servers, and prerender for pages built ahead of time; renderToString still works and is the simplest to read, which is why this lesson uses it. Which way to render each page, on every request, ahead of time, or only in the browser, is a choice of its own: Rendering strategies compares them. In a real app, a framework like Next.js or React Router runs the server for you and compiles its JSX.

hydrateRoot adopts the server's HTML

hydrateRoot(domNode, reactNode, options) takes the element that holds the server's HTML, the same JSX the server rendered, and optional settings. React then does almost what createRoot does:

1. It calls your components, with their starting state, exactly as the server did.
2. Instead of creating an element for each one, it takes the next element already on the page and checks that it matches: the same tag, the same text.
3. It keeps that element as the component's DOM node and attaches its event handling. React listens for events at the root, so the button's onClick works as soon as the button is matched.
4. Then it runs the Effects, as after any first render.

You can check that nothing is rebuilt. This example keeps the button the server sent before hydrating, then compares it with the button on the page afterwards:

1import { hydrateRoot } from "react-dom/client";2import ProductPage from "./ProductPage.jsx";3 4const root = document.getElementById("root");5const serverButton = root.querySelector("button");6 7hydrateRoot(root, <ProductPage />);8 9setTimeout(() => {10  const button = root.querySelector("button");11  console.log("Same button the server sent:", button === serverButton);12}, 500);

Line 5 finds the server's button before React runs. Line 7 hydrates. Half a second later, line 10 finds the button on the page, and line 11 compares the two with ===, which is true only for the very same element. The console shows Same button the server sent: true, and the button counts your clicks.

Now press Edit & run and swap in createRoot: createRoot instead of hydrateRoot on line 1, and createRoot(root).render(<ProductPage />); on line 7. The console shows false: createRoot clears the root and builds new elements, throwing away the server's work. The reverse is wrong too: hydrateRoot is only for HTML that React rendered. For an empty root, use createRoot.

Between the HTML arriving and hydrateRoot finishing, the page looks ready but isn't. This example pretends main.js takes 3 seconds to download. Press Run again under the result, then click Add to cart straight away:

1import { hydrateRoot } from "react-dom/client";2import ProductPage from "./ProductPage.jsx";3 4// Pretend main.js takes 3 seconds to download on a slow phone.5setTimeout(() => {6  hydrateRoot(document.getElementById("root"), <ProductPage />);7}, 3000);

Lines 5 to 7 wait 3 seconds before calling hydrateRoot. For those 3 seconds the button is plain HTML: clicks do nothing, and React never learns about them. Then the console shows Effect ran: the page is live, and clicks start to count from 0. Visitors on slow phones live in this gap. To keep it short:

• Send less JavaScript, and load code a part of the page needs only when it needs it.
• Hydrate in parts, so the important buttons work first. The last section shows how.
• Use plain links and <form> elements whose action the server handles: they work before any JavaScript has loaded.

When the server and the browser disagree

Hydration only works if the browser's first render produces the same HTML the server sent. When it doesn't, that's a hydration mismatch. This price note shows the time it was rendered:

1import { hydrateRoot } from "react-dom/client";2import PriceNote from "./PriceNote.jsx";3 4hydrateRoot(document.getElementById("root"), <PriceNote />, {5  onRecoverableError(error) {6    console.error(error.message);7  },8});

In the PriceNote.jsx tab, line 2 reads the clock and line 3 turns it into a time like 9:41. The server rendered at 9:41: look for it in the index.html tab. Your browser renders now, at a different time. The result shows your time, and the console shows React's message. Lines 4 to 8 of main.jsx pass an onRecoverableError option, which React calls for errors it recovers from; line 6 prints the message. Without the option, React reports these to the browser as uncaught errors.

Since React 19, a mismatch gives one message. It starts with what failed and lists the usual causes, then shows a diff: the components and elements down to the difference, with + before what the browser rendered and - before what the server sent. Older versions printed several separate warnings and no diff.

What React does next depends on what differs. Different text or a different element means React can't use that HTML, so it throws it away and renders that part again in the browser, up to the nearest Suspense boundary, or the whole root if there isn't one. A different attribute only gets a warning in development, and the element keeps the server's value. Try each case in the playground. The panes show the HTML the server sent, the page afterwards, which elements stayed, and React's exact words:

export default function PriceNote() {
  const now = new Date();
  const time = `${now.getHours()}:${String(now.getMinutes()).padStart(2, "0")}`;
  return (
    <main>
      <h1>Green tea</h1>
      <p>Prices checked at {time}</p>
    </main>
  );
}

Start with Different text: nothing the server sent is kept. Then Text inside Suspense: the same mismatch now costs only the paragraph, and the <h1> stays. A different attribute keeps the wrong class on the page, and An extension adds an element shows that a mismatch isn't always your code. A production build does the same work but prints only a short error code, like Minified React error #418, so fix mismatches while you develop. Each row of the table is a usual cause, why the two renders differ, and the fix:

Content only the browser knows

Some values really are different in the browser: the visitor's clock, their saved settings, the window's size. You can't make them match, but you can choose what the server renders and when the browser shows the real value. There are four ways.

1. Send the server's data with the page

If the server can know the value, make both sides render from the same data. Here the server decided the time, rendered it, and wrote it into the page as JSON, in a <script type="application/json"> after the root (see the index.html tab):

1import { hydrateRoot } from "react-dom/client";2import PriceNote from "./PriceNote.jsx";3 4// The server wrote the data it rendered with into the page.5const data = JSON.parse(document.getElementById("page-data").textContent);6 7hydrateRoot(document.getElementById("root"), <PriceNote checkedAt={data.checkedAt} />);

Line 5 reads that JSON, and line 7 passes checkedAt to PriceNote, which now shows a prop instead of reading the clock. Both sides render 9:41, and the console stays empty. Frameworks do this for you: the data a page loaded on the server travels with its HTML.

2. suppressHydrationWarning, for one element

When the difference is small and either value is fine, put suppressHydrationWarning on the element:

1import { hydrateRoot } from "react-dom/client";2import PriceNote from "./PriceNote.jsx";3 4hydrateRoot(document.getElementById("root"), <PriceNote />, {5  onRecoverableError(error) {6    console.error(error.message);7  },8});

Line 7 of PriceNote.jsx now says <p suppressHydrationWarning>. The console stays empty, but look at the result: it says 9:41, the server's time. React doesn't fix the text, it only stops checking it. The attribute works one level deep, for the element's own text and attributes, not its children's. Keep it for rare cases like this timestamp.

3. A second render in an Effect

To show the browser's value, render something both sides agree on first, then switch in an Effect, which runs only in the browser, after hydration:

1import { hydrateRoot } from "react-dom/client";2import PriceNote from "./PriceNote.jsx";3 4hydrateRoot(document.getElementById("root"), <PriceNote />, {5  onRecoverableError(error) {6    console.error(error.message);7  },8});

In PriceNote.jsx, line 4 starts time as null, so the server and the first browser render both say Prices checked a moment ago (line 12). After hydrating, the Effect on lines 5 to 8 sets the real time, and React renders again: the result shows your time. The cost is a second render and a change the visitor can see.

4. use(browser()), for a component that only works in the browser

React 19.3 added browser to react-dom for this. A component that calls use(browser()) is skipped on the server, which sends the nearest Suspense fallback instead. In the browser, use(browser()) returns at once and the component renders while the page hydrates:

1import { Suspense, use } from "react";2import { browser } from "react-dom";3import { hydrateRoot } from "react-dom/client";4 5// Pretend this visitor looked at two teas earlier.6localStorage.setItem("recent", "Jasmine tea, Earl Grey");7 8function RecentlyViewed() {9  use(browser());10  return <p>Recently viewed: {localStorage.getItem("recent")}</p>;11}12 13function ProductPage() {14  return (15    <main>16      <h1>Green tea</h1>17      <Suspense fallback={<p>Loading your recent teas...</p>}>18        <RecentlyViewed />19      </Suspense>20    </main>21  );22}23 24hydrateRoot(document.getElementById("root"), <ProductPage />);

Line 2 imports browser. Line 9 calls use(browser()) before line 10 reads localStorage, which a server doesn't have. The index.html tab holds what the server sent: the fallback from line 17, Loading your recent teas..., inside a <!--$!--> marker. The result shows the teas right away, with no mismatch: React expected the browser to render this boundary. On the server, the component must be inside a <Suspense>. Outside one, the render fails with "The server render could not complete because client rendering was requested outside a Suspense boundary." Inside one, the skip isn't a mistake, so renderToPipeableStream, renderToReadableStream and prerender report it to their onBrowserBailout option instead of onError.

For browser values that change and need a subscription, like the window's width, use useSyncExternalStore with its third argument, getServerSnapshot, as in Subscribing to external stores. Each row below is a way to render a browser-only value, what the server's HTML shows, and when it fits:

Hydrating one part at a time

A Suspense boundary does more than limit what a mismatch costs. React hydrates each boundary on its own, so one slow part doesn't hold up the rest. This is called selective hydration. In this page, the reviews' code takes 3 seconds to download. Click Cart right away, then Helpful, then Helpful again after the console says Reviews hydrated:

1import { Suspense, lazy } from "react";2import { hydrateRoot } from "react-dom/client";3import Header from "./Header.jsx";4 5const Reviews = lazy(() => slowDownload(import("./Reviews.jsx")));6 7// Pretends the reviews' code takes 3 seconds to download.8function slowDownload(file) {9  return new Promise((resolve) => setTimeout(() => resolve(file), 3000));10}11 12function ProductPage() {13  return (14    <main>15      <Header />16      <Suspense fallback={<p>Loading reviews...</p>}>17        <Reviews />18      </Suspense>19    </main>20  );21}22 23hydrateRoot(document.getElementById("root"), <ProductPage />);

Line 5 loads Reviews.jsx with lazy, and lines 8 to 10 make the download take 3 seconds. Lines 16 to 18 put the reviews in a Suspense boundary. The index.html tab holds the server's HTML for both parts, the reviews between <!--$--> and <!--/$-->.

Line 23 hydrates. The header is ready at once: the console shows Header hydrated, and Cart counts. The reviews keep the server's HTML, so the visitor reads them, but Helpful does nothing for 3 seconds. When the code arrives, the console shows Reviews hydrated and Helpful counts too.

React also hydrates the part you use first. While some boundaries are still server HTML:

• If you click inside one whose code has arrived, React hydrates that boundary right away, then runs the click, so it isn't lost.
• If its code hasn't arrived, React can't, and in React 19.3.1 the click is dropped, as you saw with Helpful. For hover and focus, React keeps the latest event and replays it once the boundary hydrates.

You can read this rule in React's event code, in lines 196 to 223 of ReactDOMEventListener.js. With streaming, a boundary's HTML can arrive late too, after the rest of the page; Streaming server rendering covers it.

A shop header that hydrates cleanly

Here is a header from a real shop, written the way people often first write it. It greets a returning visitor by the name saved in localStorage, and shows their cart count. It checks typeof window because the server has no localStorage:

1import { hydrateRoot } from "react-dom/client";2import ShopHeader from "./ShopHeader.jsx";3 4// Pretend Asha visited before and left 3 teas in her cart.5localStorage.setItem("name", "Asha");6localStorage.setItem("cart", "3");7 8hydrateRoot(document.getElementById("root"), <ShopHeader />, {9  onRecoverableError(error) {10    console.error(error.message);11  },12});

In ShopHeader.jsx, lines 2 and 3 take one branch on the server, null and 0, and the other in the browser, Asha and 3. So the server sent Welcome and Cart (0), and the browser renders Welcome back, Asha and Cart (3). The console shows the mismatch on the heading, and React throws away the whole header and builds it again. The result looks right, but the server's HTML was wasted, and visitors see Cart (0) until the JavaScript arrives.

The two values need different fixes. The server knows the cart; only the browser knows the saved name:

1import { hydrateRoot } from "react-dom/client";2import ShopHeader from "./ShopHeader.jsx";3 4localStorage.setItem("name", "Asha");5 6// The server knew Asha's cart and wrote it into the page.7const data = JSON.parse(document.getElementById("page-data").textContent);8 9hydrateRoot(document.getElementById("root"), <ShopHeader cart={data.cart} />, {10  onRecoverableError(error) {11    console.error(error.message);12  },13});

The cart comes from the server. A real server reads it from the visitor's session; here it rendered Cart (3) and wrote {"cart":3} into the page. Line 7 of main.jsx reads it, and line 9 passes it as a prop, so both sides render Cart (3). The greeting is browser-only: in ShopHeader.jsx, Greeting calls use(browser()) on line 5, and lines 12 to 14 wrap it in a Suspense boundary whose fallback is the plain Welcome. The console stays empty, the server's button is kept, and the greeting appears as soon as the page hydrates.

Common mix-ups

• "Hydration renders the page again from scratch." No. It renders your components, but keeps the elements already on the page and attaches handlers to them. The adopt example logs true.
• "Server rendering makes the page work sooner." No. It makes the page show sooner. It works only once the JavaScript has loaded and hydrated it, so clicks before that do nothing.
• "suppressHydrationWarning fixes a mismatch." No. It hides the warning for one element and keeps the server's value. The page still says 9:41.
• "React corrects attributes that differ." No. It warns in development and leaves the server's attribute in place.
• "Effects run on the server too." No. Neither useEffect nor useLayoutEffect runs on the server, which is why a value set in an Effect is safe from mismatches.
• "A typeof window check makes a component safe to render on the server." No. In render, it makes the server and the browser take different branches, which is a mismatch.
• "Mismatches only matter in development." No. A production build throws away the HTML and renders again too; it just prints a short error code instead of the diff.

Practice exercises

Each hydration exercise has an index.html tab with the HTML the server sent, and a main.jsx that runs in the browser. Press Edit & run, change the code, and watch the result and the console. Guess first, then use the hints.

import { renderToString } from "react-dom/server";

function CartBadge() {
  const count = 3;
  return <p>Items: {count}</p>;
}

console.log(renderToString(<CartBadge />));

1import { renderToString } from "react-dom/server";2 3function CartBadge() {4  const count = 3;5  return <p>Items: {count}</p>;6}7 8console.log(renderToString(<CartBadge />));

import { hydrateRoot } from "react-dom/client";
import ThemeLink from "./ThemeLink.jsx";

// This visitor picked the dark theme on an earlier visit.
localStorage.setItem("theme", "dark");

hydrateRoot(document.getElementById("root"), <ThemeLink />);

setTimeout(() => {
  console.log("The link's class:", document.querySelector("a").className);
}, 500);

1import { hydrateRoot } from "react-dom/client";2import ThemeLink from "./ThemeLink.jsx";3 4// This visitor picked the dark theme on an earlier visit.5localStorage.setItem("theme", "dark");6 7hydrateRoot(document.getElementById("root"), <ThemeLink />);8 9setTimeout(() => {10  console.log("The link's class:", document.querySelector("a").className);11}, 500);

1import { hydrateRoot } from "react-dom/client";2import Cart from "./Cart.jsx";3 4hydrateRoot(document.getElementById("root"), <Cart items={[]} />, {5  onRecoverableError(error) {6    console.error(error.message);7  },8});

1import { hydrateRoot } from "react-dom/client";2import Cart from "./Cart.jsx";3 4const data = JSON.parse(document.getElementById("page-data").textContent);5 6hydrateRoot(document.getElementById("root"), <Cart items={data.items} />, {7  onRecoverableError(error) {8    console.error(error.message);9  },10});

1import { hydrateRoot } from "react-dom/client";2 3function Greeting() {4  if (typeof window === "undefined") {5    return <h1>Hello</h1>;6  }7  const hour = new Date().getHours();8  return <h1>{hour < 12 ? "Good morning" : "Good afternoon"}</h1>;9}10 11hydrateRoot(document.getElementById("root"), <Greeting />, {12  onRecoverableError(error) {13    console.error(error.message);14  },15});

1import { useEffect, useState } from "react";2import { hydrateRoot } from "react-dom/client";3 4function Greeting() {5  const [greeting, setGreeting] = useState("Hello");6  useEffect(() => {7    const hour = new Date().getHours();8    setGreeting(hour < 12 ? "Good morning" : "Good afternoon");9  }, []);10  return <h1>{greeting}</h1>;11}12 13hydrateRoot(document.getElementById("root"), <Greeting />, {14  onRecoverableError(error) {15    console.error(error.message);16  },17});

import { Suspense } from "react";
import { hydrateRoot } from "react-dom/client";

function PriceNote() {
  const now = new Date();
  const time = `${now.getHours()}:${String(now.getMinutes()).padStart(2, "0")}`;
  return (
    <main>
      <h1>Green tea</h1>
      <Suspense fallback={<p>Checking prices...</p>}>
        <p>Prices checked at {time}</p>
      </Suspense>
    </main>
  );
}

const root = document.getElementById("root");
const serverHeading = root.querySelector("h1");

// An empty handler keeps the mismatch report out of the console.
hydrateRoot(root, <PriceNote />, { onRecoverableError() {} });

setTimeout(() => {
  console.log("Same <h1>:", root.querySelector("h1") === serverHeading);
}, 500);

1import { Suspense } from "react";2import { hydrateRoot } from "react-dom/client";3 4function PriceNote() {5  const now = new Date();6  const time = `${now.getHours()}:${String(now.getMinutes()).padStart(2, "0")}`;7  return (8    <main>9      <h1>Green tea</h1>10      <Suspense fallback={<p>Checking prices...</p>}>11        <p>Prices checked at {time}</p>12      </Suspense>13    </main>14  );15}16 17const root = document.getElementById("root");18const serverHeading = root.querySelector("h1");19 20// An empty handler keeps the mismatch report out of the console.21hydrateRoot(root, <PriceNote />, { onRecoverableError() {} });22 23setTimeout(() => {24  console.log("Same <h1>:", root.querySelector("h1") === serverHeading);25}, 500);

1import { hydrateRoot } from "react-dom/client";2 3localStorage.setItem("name", "Asha");4 5function ShopHeader({ cart }) {6  const greeting = typeof window === "undefined" ? "Welcome" : `Welcome back, ${localStorage.getItem("name")}`;7  return (8    <header>9      <h1>{greeting}</h1>10      <button>Cart ({cart})</button>11    </header>12  );13}14 15hydrateRoot(document.getElementById("root"), <ShopHeader cart={0} />, {16  onRecoverableError(error) {17    console.error(error.message);18  },19});

1import { useEffect, useState } from "react";2import { hydrateRoot } from "react-dom/client";3 4localStorage.setItem("name", "Asha");5 6function ShopHeader({ cart }) {7  const [greeting, setGreeting] = useState("Welcome");8  useEffect(() => {9    setGreeting(`Welcome back, ${localStorage.getItem("name")}`);10  }, []);11  return (12    <header>13      <h1>{greeting}</h1>14      <button>Cart ({cart})</button>15    </header>16  );17}18 19const data = JSON.parse(document.getElementById("page-data").textContent);20 21hydrateRoot(document.getElementById("root"), <ShopHeader cart={data.cart} />, {22  onRecoverableError(error) {23    console.error(error.message);24  },25});

Check your understanding

For each question, think about two runs: what the server rendered, and what the browser renders while hydrating.

Key takeaways

• Server rendering runs your components on a server and sends their HTML, so the page shows before the JavaScript loads. The HTML holds elements, text, and starting state; never handlers or Effects.
• hydrateRoot runs the same components in the browser and adopts the server's elements: it keeps them, attaches event handling, then runs Effects. Until it runs, the page looks ready but doesn't respond.
• The browser's first render must match the server's HTML. React 19 reports a mismatch once, with a diff, and renders that part again up to the nearest Suspense boundary. Attributes that differ only get a warning and stay wrong.
• For values only the browser knows: send the server's data with the page, use suppressHydrationWarning for one harmless difference, set them in an Effect, or make the component browser-only with use(browser()).
• Suspense boundaries hydrate on their own. The rest of the page works while one boundary waits for its code, and a click on a boundary whose code is ready makes React hydrate it first.

Coming next: Streaming server rendering. Instead of waiting for the whole page, the server sends the HTML in pieces, each Suspense boundary as soon as its data is ready.