Hydration
The process where client-side JavaScript takes over a static HTML page rendered by the server to make it interactive.
Detailed Explanation
After the server sends a pre-rendered HTML page (SSR), the browser downloads the JavaScript bundle. 'Hydration' is the step where the framework (like React or Vue) attaches event listeners and state management to the existing HTML elements. If the server-rendered HTML doesn't perfectly match what the client expects, a 'hydration mismatch' error occurs, which can lead to broken UI or performance issues.
Quick Summary
Hydration is the step that turns server-rendered HTML into a live, interactive React/Vue/Svelte app by attaching event handlers and state to the existing DOM nodes. The HTML is already painted; hydration just wires it up.
Key Takeaways
- Hydration runs after the HTML is parsed and after the JS bundle has loaded, it is gated by both.
- The component tree on the client must produce the same markup as the server, or you get a mismatch warning.
- Hydration is expensive because every component runs at least once on the client, even if nothing changed.
- Partial hydration and React Server Components skip work for components that have no client interactivity.
- Time-to-interactive on SSR apps is largely a function of how big the hydration step is.
When to use it
- Marketing pages that need fast first paint via SSR plus rich interactivity once loaded.
- E-commerce listings where filters and cart updates need client state on top of crawlable HTML.
- Apps using React 19's hydrateRoot or Next.js App Router's client component boundaries.
- Progressive enhancement strategies where components hydrate lazily on scroll or interaction.
Common Mistakes
- Rendering Date.now() or Math.random() on the server, then producing different output on the client and triggering a mismatch.
- Reading window or document during render, they do not exist on the server.
- Hydrating every component on the page eagerly when most are static and could remain as plain HTML.
- Conditional rendering based on typeof window === 'undefined' that flickers because the client first matches the server, then re-renders.
Hydration, Frequently Asked
What is a hydration mismatch?
It is an error reported when the DOM the client renders does not match the HTML the server sent. The framework has to throw away the server output and re-render from scratch, which causes visible flashes and wastes work.
Can I skip hydration entirely?
Only if the page has no client-side interactivity. Tools like Astro's islands architecture and React Server Components let you ship static HTML for non-interactive parts and hydrate only what needs to be live.
Is hydration the same as rendering?
No. Rendering produces the HTML. Hydration runs after rendering and attaches event listeners, state, and effects to the already-rendered DOM. They are two separate phases of the same component tree.