Hydration
Hydration attaches client-side application state and interaction behavior to HTML that was rendered before the browser application started.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/hydration/
01What it means
Hydration is the client process that activates server-rendered or pre-rendered HTML by reconciling it with application code, restoring state, and attaching behavior such as event handlers. It aims to reuse existing markup rather than discard and recreate it. Partial and selective approaches reduce how much of the page must hydrate.[1][2]
- 01Render HTMLServer or build-time state
- 02Display markupUseful pixels before activation
- 03Load code + dataReproduce client state
- 04ReconcileMatch components to DOM
- 05Attach behaviorEvents and interactions
Mismatch handling and interaction-delay telemetry reveal when server and client output diverge.
02Why it matters
Hydration can combine early HTML with rich client interaction, but it often sends similar rendering logic and data twice and consumes main-thread time after content appears. Users may see controls before those controls can respond.
03When to use it
Use hydration when server or static HTML must become part of a stateful client application. Prefer native HTML, small enhancements, or selectively hydrated components when most content does not require a persistent client runtime.
04How it works
- The server or build process renders HTML from application state.
- The response carries the markup plus enough data and scripts to reproduce that state.
- The browser displays the HTML while client code downloads and executes.
- The client matches its component structure to the existing DOM and attaches behavior.
- Mismatch handling and telemetry reveal inconsistent rendering or delayed interaction.
05A practical example
A news page renders article text and subscription controls on the server. The article remains plain HTML, while only the pricing selector and sign-up dialog hydrate when needed, reducing the period in which visible controls are inactive.
06Where it breaks
Hydration can duplicate work, increase JavaScript and serialized data, create mismatches between server and client output, and delay responsiveness. Framework behavior differs, so the label alone does not specify cost or scope.
Common mistakes
- Assuming visible server-rendered controls are already interactive.
- Hydrating an entire page when only a few components need client state.
- Generating nondeterministic server and client markup that cannot reconcile.
- Measuring first paint while ignoring interaction delay and main-thread work.
07Sources
- Rendering on the Webweb.dev · Official technical guidanceRendering on the Web
- hydrateRootReact · Official framework documentationhydrateRoot