What is hydration in React and Next.js?
The commands on this page have not been executed by our verification runner yet.updated 2026-10-20
- tool
- React
- versions
- React 18, React 19
- os
- any
Hydration is the step in which React, running in the browser, takes HTML that was already rendered on the server and attaches its components, state and event handlers to the existing DOM instead of building the DOM again. The page is visible as soon as the HTML arrives and becomes interactive once hydration finishes.
How it works
- The server renders the component tree to HTML (
renderToPipeableStream, or a framework such as Next.js). - The browser shows that HTML immediately.
- The JavaScript bundle loads and calls
hydrateRoot(container, <App />). - React renders the same tree in memory, walks the existing DOM, checks that it matches, and wires up event listeners.
If the first client render produces different output, React reports a hydration error and re-renders that part on the client.
Related terms
| Term | Meaning |
|---|---|
| SSR | server-side rendering: HTML is produced per request |
| SSG | static generation: HTML is produced at build time |
| Hydration mismatch | server HTML differs from the first client render |
| Selective hydration | React 18+ hydrates parts of the page as their code arrives, inside Suspense boundaries |
| React Server Components | components that run only on the server and ship no JavaScript, so they need no hydration |
Rule for hydration-safe components: the first render must not depend on anything that only the browser knows (window size, local time, localStorage). Read those values in useEffect, after hydration.
Sources
Related pages
errors · nextjsHydration failed because the server rendered HTML didn't match the clientNext.js and React 19 report Hydration failed when server HTML differs from the first client render: Date.now(), window checks, locale formats, bad nesting.errors · reactEach child in a list should have a unique "key" propReact warns Each child in a list should have a unique "key" prop when map() returns elements without key. Use a stable id from your data, not the index.errors · reactError: Too many re-renders. React limits the number of renders to prevent an infinite loop.React throws Too many re-renders when a component sets state during render, often onClick={setCount(1)} instead of onClick={() => setCount(1)}. How to fix it.