Skip to content
fa
Search Frontend Atlas
Search questions and concepts across the handbook.
Frameworks & UI Architectureadvanced12 min read

What is hydration, and why do islands architectures reduce client JavaScript?

Explain server-rendered HTML, client reconciliation, hydration boundaries, and selective interactivity.

Useful prerequisites

A server can send HTML that is already visible before the browser has downloaded the JavaScript for the page. Hydration connects that existing HTML to client-side code so it can respond to interactions. An islands architecture takes a more selective approach: only the parts that need browser-side behaviour receive it.

A server can send HTML that is already visible before the browser has downloaded the JavaScript for the page. Hydration connects that existing HTML to client-side code so it can respond to interactions. An islands architecture takes a more selective approach: only the parts that need browser-side behaviour receive it.

The quick version

Hydration attaches client-side behavior to server-rendered markup and reconciles it with the framework’s expected tree. Islands architectures hydrate only selected interactive regions, leaving static content as HTML.

Build the mental model

Hydration requires server and client output to agree. Nondeterministic dates, random IDs, browser-only state, or locale differences can create mismatches. Islands reduce shipped JavaScript but introduce boundaries for shared state and interaction.

See it in code

<StaticArticle />
<SearchPanel client:idle />

Where it gets tricky

Hydration mismatches are frequently caused by values that differ between server and browser: random numbers, current time, locale formatting, viewport reads, and browser storage. Keep browser-only reads behind client lifecycle boundaries. Islands also need explicit data boundaries; two independently hydrated components do not automatically share one in-memory state store.

A common misunderstanding

SSR does not mean zero JavaScript, and hydration is not the same as rendering HTML.

What this changes in an application

Choose hydration strategies per interaction urgency. Measure transferred JavaScript, hydration cost, and time to usable controls.

Questions worth exploring next

  • What causes a hydration mismatch?
  • When would client:visible be inappropriate?

References and next steps

Explore next