Ch. 3 · React

React Hydration and Matching Initial Content

What causes React hydration mismatch errors: dates, random ids, window checks and bad HTML nesting, plus fixes with useId, effects and Suspense.

~7 min readadvancedupdated Nov 1, 2026

“Your server-rendered page logs a hydration mismatch. What does that mean, and how do you fix it without just hiding the warning?” The error shows up in Next.js, Remix and custom SSR setups alike, and fixing it properly depends on understanding what hydration does and why the first client render is special.

A strong answer names the typical causes from memory and explains the correct fix for each, rather than reaching for suppressHydrationWarning or turning off server rendering. You need two pieces of background: how server rendering differs from client rendering (the browser gets HTML first and JavaScript afterwards), and the basics of useState and useEffect.

What hydration expects from the first client render

Hydration is React adopting server-rendered HTML: instead of creating DOM nodes, it walks the existing ones, attaches event handlers, and expects its first client render to produce exactly the same markup. A mismatch happens when render output depends on something that differs between server and client, such as the current time, Math.random(), window or localStorage, the user’s locale or time zone, or invalid HTML that the browser’s parser rearranged. Fix it by making the first client render identical to the server output, then updating client-only values in an effect after hydration, and by using useId for generated ids.

A greeting that says morning in UTC and afternoon in Tokyo

The server runs your components and sends HTML. The browser displays it immediately. When the JavaScript loads, hydrateRoot(container, <App />) renders the same tree on the client and matches it, node by node, against the existing DOM.

function Greeting() {
  const hour = new Date().getHours();
  return <p>{hour < 12 ? 'Good morning' : 'Good afternoon'}</p>;
}
JSX

If the server runs in UTC and the user is in Tokyo, the server might say “Good morning” while the browser computes “Good afternoon”. React finds different text and reports Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. It throws away the server HTML for the nearest Suspense boundary (or the whole root) and renders it again on the client. That means a visual flash, lost performance and possibly lost focus or scroll position.

Attribute mismatches behave differently, and more quietly. If only an attribute differs (say id="a" on the server and id="b" on the client), React 19 keeps the server’s DOM node, logs A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up. in development, and leaves the server’s value in the DOM. Running both cases through renderToString and hydrateRoot in jsdom with React 19.3 shows exactly that: the text case replaced the <p>, while the attribute case kept id="a".

Hydration also attaches events only after it reaches a component, so mismatches tend to appear exactly where you most need the page to be interactive quickly.

Habits that cause mismatches or hide them

  • Checking typeof window in render. The server renders one branch, the client another, and that mismatch is guaranteed.
  • Blanket suppressHydrationWarning. It only works one level deep on a single element’s text or attributes, and it hides real bugs. React does not patch the suppressed text either, so the server’s version stays on screen until the next render changes it. It is appropriate for a timestamp you deliberately let differ.
  • Disabling SSR for the whole page. It removes the symptom and the benefits of server rendering.
  • Generating ids with a counter. Module-level counters drift between server and client and across requests. Use useId.
  • Blaming React for extension-injected markup. React 19 tolerates many unexpected tags from extensions and third-party scripts in <head> and <body>, but it cannot fix mismatches in your own components.

Finding and fixing the value that differs

Read the diff and find what produced the value

React 19 prints the server and client values with a diff. Search for what produced that value. Common culprits:

<span>{Date.now()}</span>                       // time
<div id={`field-${Math.random()}`} />           // randomness
{typeof window !== 'undefined' && <Banner />}   // environment branching
<p>{price.toLocaleString()}</p>                  // locale differences
<p><div>nested block</div></p>                   // invalid HTML nesting
JSX

Generate ids with useId

useId generates ids from the component’s position in the tree, so server and client agree:

function EmailField() {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}
JSX

Do not use it for list keys; keys should come from data.

Switch to client-only values after hydration

Render the server-safe version first, then switch in an effect, which runs only in the browser after hydration:

function LocalTime({ iso }) {
  const [text, setText] = useState(null);
  useEffect(() => {
    setText(new Date(iso).toLocaleTimeString());
  }, [iso]);
  return <time dateTime={iso}>{text ?? iso.slice(11, 16) + ' UTC'}</time>;
}
JSX

Server and first client render both output the UTC fallback, so hydration matches. The local time appears right after. For a value from an external source like localStorage or a media query, useSyncExternalStore with a getServerSnapshot gives the same guarantee; see external store subscriptions.

Fix nesting that the browser’s parser rearranges

The browser’s parser repairs invalid nesting before React sees the DOM. A <div> inside a <p>, an <a> inside an <a>, or a <tr> directly inside <table> without <tbody> becomes a different DOM tree than React expects. Correct the markup; no runtime trick will fix this.

A shipping countdown that reset the buy-box

Picture an e-commerce site that shows “Free shipping ends in 3h 12m” using a countdown computed in render. On product pages, React logs mismatches and the whole buy-box re-renders on the client, occasionally wiping a quantity the user had already changed while the page was still loading.

The countdown reads Date.now() during render. The server’s value is seconds or minutes older than the client’s by the time the bundle loads, so the text never matches.

The fix renders a stable placeholder on both sides and starts the countdown after hydration:

function Countdown({ endsAt }) {
  const [remaining, setRemaining] = useState(null);

  useEffect(() => {
    const tick = () => setRemaining(Math.max(0, endsAt - Date.now()));
    tick();
    const id = setInterval(tick, 1000);
    return () => clearInterval(id);
  }, [endsAt]);

  if (remaining === null) return <span>Free shipping today</span>;
  return <span>Free shipping ends in {format(remaining)}</span>;
}
JSX

The buy-box now hydrates cleanly, and the countdown appears a moment later without disturbing anything around it. Wrapping slow, non-critical parts of the page in <Suspense> boundaries also lets React hydrate the buy-box first.

Catching mismatches in a test with onRecoverableError

Render a component on the server and hydrate it in a test environment to catch mismatches automatically:

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

const container = document.createElement('div');
container.innerHTML = renderToString(<App />);
document.body.appendChild(container);

const errors = [];
hydrateRoot(container, <App />, {
  onRecoverableError: error => errors.push(error),
});
// after React has finished hydrating, expect(errors).toEqual([])
JSX

In React 19, text and structure mismatches reach onRecoverableError, but attribute mismatches only go to console.error, so a thorough test also spies on console.error and fails on any call. Running this in a jsdom test (inside act to flush) with the clock or locale mocked differently on each side reproduces time-zone bugs before they reach production. In the browser, the development console shows the diff directly.

Interview question: “Sign in” on the server, a name on the client

A header shows “Sign in” on the server and the user’s name on the client, read from localStorage in render. Hydration fails. Give the immediate fix and the better architectural fix.

Answer: the quick fix and the real one

The immediate fix is to make the first client render match the server: render “Sign in” (or a neutral placeholder of the same size) initially, and read localStorage in an effect or through useSyncExternalStore with a server snapshot of null, then show the name after hydration. The architectural fix is to stop storing the session only in the browser: put it in an HTTP-only cookie so the server knows who the user is and renders their name directly. Then server and client agree from the start, there is no flash from “Sign in” to the name, and the token is not exposed to scripts.

Selective hydration, Server Components and production

What is selective hydration? With Suspense boundaries, React 18+ hydrates parts of the page independently and prioritises the part the user interacts with. See Suspense boundaries.

Can Server Components cause mismatches? Their output is already HTML and serialised data, so they do not hydrate themselves; mismatches come from the Client Components they render. See Server Components boundaries.

Why not render client-only components with useEffect and a mounted flag everywhere? It works but shifts all that content to after hydration, hurting performance and causing layout shifts. Use it only for genuinely client-dependent pieces.

Does a mismatch break the page in production? For text and structure mismatches React recovers by client-rendering the affected boundary, so the page works, but you lose the SSR benefit for that subtree and may see a flash. Attribute mismatches are not recovered at all: the server’s value stays in the DOM.

Further reading on SSR and Suspense

Practise with the React interview questions and the React MCQs. Related notes: Suspense boundaries, Server Components boundaries and external store subscriptions. Official reference: the hydrateRoot reference on react.dev.

More in React

read ✓React · hard

React Context Splitting for Performance

Why every React context consumer re-renders when any part of the value changes, and how splitting state, actions and slow-changing data fixes it.

~6 min readread →
read ✓React · mid

React lazy Loading and Code Splitting

Split React bundles with lazy and Suspense, preload chunks before the click, and handle the chunk-load failures that follow every deploy.

~7 min readread →
esc