Hydration
Hydration is the process where client-side JavaScript takes over a server-rendered HTML page, attaching event handlers and state management to make the static page interactive. The page looks ready before it actually is.
§ 1 Definition
Hydration (or rehydration) is the technique used in server-side rendered (SSR) applications where the HTML pre-rendered on the server is made interactive on the client. The server sends fully rendered HTML to the browser, which displays immediately (fast First Contentful Paint). Then the JavaScript bundle for the application downloads, executes, and attaches event handlers, state, and effects to the existing DOM nodes. During hydration, the framework (React, Vue, Angular) calculates what the component tree should look like based on the current state, then matches it against the existing DOM. If there are mismatches (hydration mismatches), the framework discards the server-rendered HTML and re-renders on the client, which is wasteful. Hydration is the source of the 'uncanny valley' problem in SSR apps: the page appears fully loaded but is not interactive until hydration completes. This period between visible render and interactivity is called the uncanny valley of SSR.
§ 2 Hydration Mismatches
Hydration mismatches occur when the server-rendered HTML differs from what React expects to render on the client. Common causes include: browser-only APIs (localStorage, window.innerWidth) used during render, timestamp or random value generation (new Date(), Math.random()), browser extensions that modify the DOM, and CSS-in-JS libraries that inject styles differently on server vs client. React logs warnings for mismatches, and the framework falls back to client-only rendering for the mismatched parts, which defeats the purpose of SSR.
§ 3 Alternatives and Improvements
Full hydration (hydrating the entire page as one unit) is increasingly seen as inefficient. Alternatives include progressive hydration (hydrating components in order of priority), partial hydration (only hydrating interactive components, as in Astro's island architecture), and selective hydration (streaming hydration as components become available, as in React 18's streaming SSR). React Server Components represent a different approach: avoid hydration entirely for server components that do not need interactivity.
§ 4 Note
§ 5 Common questions
- Q. How do I fix hydration mismatches?
- A. Ensure server and client render the same thing. Do not use browser-only APIs during render. Use useEffect for browser-dependent code. For dynamic content (dates, random values), render them on the client only or use suppressHydrationWarning as a last resort.
- Q. Is hydration bad for performance?
- A. Yes, for large pages. Hydrating a massive component tree blocks the main thread and delays interactivity. This is why frameworks are moving toward partial hydration, selective hydration, and server components.
- Hydration attaches JavaScript behavior to server-rendered HTML. The page is visible but not yet interactive.
- Hydration mismatches occur when server and client HTML disagree. They defeat SSR benefits.
- Full hydration is being replaced by progressive, selective, and partial hydration patterns.
Atomic Glue designs hydration strategies that minimize the uncanny valley problem. We use React Server Components to eliminate hydration for non-interactive parts of the page, keeping the JavaScript payload focused on what actually needs interactivity. This means your site looks loaded and is loaded faster. Our team also debugs common hydration mismatch issues from browser extensions, dynamic content, and third-party scripts. This optimization directly improves Core Web Vitals and user experience.
Get in touchHydration is the process where client-side JavaScript takes over a server-rendered HTML page, attaching event handlers and state management to make the static page interactive. The page looks ready before it actually is.
Category: Front End (also: Software Engineering)
Author: Atomic Glue Development Team
## Definition
Hydration (or rehydration) is the technique used in server-side rendered (SSR) applications where the HTML pre-rendered on the server is made interactive on the client. The server sends fully rendered HTML to the browser, which displays immediately (fast First Contentful Paint). Then the JavaScript bundle for the application downloads, executes, and attaches event handlers, state, and effects to the existing DOM nodes. During hydration, the framework (React, Vue, Angular) calculates what the component tree should look like based on the current state, then matches it against the existing DOM. If there are mismatches (hydration mismatches), the framework discards the server-rendered HTML and re-renders on the client, which is wasteful. Hydration is the source of the 'uncanny valley' problem in SSR apps: the page appears fully loaded but is not interactive until hydration completes. This period between visible render and interactivity is called the uncanny valley of SSR.
## Hydration Mismatches
Hydration mismatches occur when the server-rendered HTML differs from what React expects to render on the client. Common causes include: browser-only APIs (localStorage, window.innerWidth) used during render, timestamp or random value generation (new Date(), Math.random()), browser extensions that modify the DOM, and CSS-in-JS libraries that inject styles differently on server vs client. React logs warnings for mismatches, and the framework falls back to client-only rendering for the mismatched parts, which defeats the purpose of SSR.
## Alternatives and Improvements
Full hydration (hydrating the entire page as one unit) is increasingly seen as inefficient. Alternatives include progressive hydration (hydrating components in order of priority), partial hydration (only hydrating interactive components, as in Astro's island architecture), and selective hydration (streaming hydration as components become available, as in React 18's streaming SSR). React Server Components represent a different approach: avoid hydration entirely for server components that do not need interactivity.
## Note
Common misunderstanding: Hydration is not the same as rendering. Rendering produces the HTML or virtual DOM tree. Hydration attaches behavior to existing HTML. Another misconception: a hydrated page is immediately interactive. It is not. Hydration happens in a single synchronous pass. The browser may appear frozen during this process because JavaScript is executing on the main thread. The Time to Interactive metric captures this delay.
## Common questions
Q: How do I fix hydration mismatches?
A: Ensure server and client render the same thing. Do not use browser-only APIs during render. Use useEffect for browser-dependent code. For dynamic content (dates, random values), render them on the client only or use suppressHydrationWarning as a last resort.
Q: Is hydration bad for performance?
A: Yes, for large pages. Hydrating a massive component tree blocks the main thread and delays interactivity. This is why frameworks are moving toward partial hydration, selective hydration, and server components.
## Key takeaways
- Hydration attaches JavaScript behavior to server-rendered HTML. The page is visible but not yet interactive.
- Hydration mismatches occur when server and client HTML disagree. They defeat SSR benefits.
- Full hydration is being replaced by progressive, selective, and partial hydration patterns.
## Related entries
- [React Server Components](atomicglue.co/glossary/react-server-components)
- [React](atomicglue.co/glossary/react)
- [Next.js](atomicglue.co/glossary/next-js)
Last updated June 2026. Permalink: atomicglue.co/glossary/hydration