What is Partial Hydration?
Definition
Partial hydration is an approach in which only the components that need interactivity on a server-rendered or prebuilt page are hydrated with JavaScript, while the rest of the content stays as plain HTML. At the level of page architecture the idea is known as islands architecture: independent interactive islands within an otherwise static page. The goal is to cut the amount of JavaScript the browser downloads and executes.
Also known as: islands architecture, component islands, island hydration
The problem full hydration leaves behind
With classic server-side rendering, the HTML arrives ready, but during hydration the framework re-runs the entire component tree in the browser. On a long article, the only interactive parts might be the menu toggle and the comment form, yet the component code for every heading, paragraph and footer is still downloaded and executed. The cost scales with how big the page is, not with how interactive it is. Partial hydration flips that: sections with no interactivity ship no JavaScript at all.
Islands architecture
Etsy frontend architect Katie Sylor-Miller used the phrase "component islands" in 2019, and Preact creator Jason Miller expanded the idea in an August 2020 article that popularised the name "islands architecture". In this model the page is a sea of server-rendered static HTML, and each interactive component is a self-contained island within it. Every island loads its own code and hydrates on its own schedule, so a slow or broken island doesn't hold up the others.
Picture a news article: the header menu, the search box and the comment form are islands; the story text, images, related links and footer are plain HTML. A reader can start on the first paragraph before any island has hydrated, and nothing is lost.
Astro: choosing when each island wakes up
Astro applies this model by default. Components are rendered to HTML and CSS and client-side JavaScript is stripped out. A component that needs to be interactive is opted in with a client:* directive, which also sets when it hydrates:
---
import Header from "../components/Header.astro";
import Cart from "../components/Cart.jsx";
import Search from "../components/Search.jsx";
import Comments from "../components/Comments.jsx";
---
<Header /> <!-- HTML only -->
<Cart client:load /> <!-- on page load -->
<Search client:idle /> <!-- when the browser is idle -->
<Comments client:visible /> <!-- when scrolled into view -->Astro also offers server islands through the server:defer directive: dynamic sections such as a personalised avatar or live stock level are rendered separately on the server and slotted in without blocking the rest of the page. See the Astro documentation for details.
Telling similar terms apart
| Term | Question it answers |
|---|---|
| Partial hydration | Which components get hydrated at all? |
| Progressive hydration | In what order, and when, are components hydrated? |
| Selective hydration | In React, which Suspense-bounded section gets priority? |
| Resumability | Can the client pick up where the server left off without hydrating? (Qwik) |
React Server Components produce a similar effect inside a React tree: server components never send their code to the browser, and only client components hydrate. Another frequent mix-up is treating progressive enhancement and progressive hydration as one idea. Progressive enhancement is the principle that a page keeps its core function without JavaScript; islands fit that principle well, but don't guarantee it on their own.
Trade-offs
Because islands are independent, sharing state between them takes extra work: if the add-to-cart button and the cart counter in the header live in different islands, they need a shared store or custom events to stay in sync. On dashboard-style apps where most of the screen is interactive, islands multiply and the advantage fades; a single-page application may be the more natural fit there. On content-heavy sites, though, less code competing for the main thread usually means better interaction latency, as measured by INP.