Islands Architecture: Selective Hydration

Islands Architecture, coined by Jason Miller in 2020, treats a web page as mostly static HTML with isolated "islands" of interactivity embedded in it. The static ocean of HTML is sent to the browser as-is. Only the interactive islands download and execute JavaScript, making the JavaScript payload proportional to actual interactivity.

Each island is an independently hydrated component. The server renders the island's initial HTML along with the rest of the page. When the island's JavaScript loads, it hydrates only that component subtree. The HTML surrounding the islands is never touched by JavaScript — it is truly static.

On a blog post page with Islands Architecture, the JavaScript payload might be 5kb for a single like-button island. The same page built as a React SPA might ship 200kb+ of JavaScript to hydrate the entire page. The islands approach makes the payload proportional to interactivity, not page size.

Astro, the leading Islands Architecture framework, supports islands built with different frameworks on the same page. You can have a React island next to a Vue island next to a vanilla JavaScript island. Each island is independently bundled, so users only download the framework code used by visible islands.

The client:load directive hydrates the island immediately when the page loads. Use this for islands that are immediately visible and interactive, such as a navigation menu or a hero section with a search input. This is the highest-priority hydration strategy.

The client:idle directive waits until the browser's main thread is idle (after the critical content has loaded) before hydrating the island. This is ideal for widgets below the fold or secondary interactions that are not needed immediately, such as a social share bar.

The client:visible directive uses an Intersection Observer to hydrate the island only when it scrolls into the viewport. This is ideal for islands deep in the page — a comment section, a related products carousel — that most users may never reach. JavaScript is not even loaded until needed.

The client:only directive skips server-side rendering entirely and only renders the island in the browser. This is necessary for components that use browser-only APIs (window, document) or that depend on client-side state at mount time. The trade-off is no server-rendered HTML for that island.

Islands Architecture solves the full hydration problem by ensuring JavaScript is loaded and executed only for genuinely interactive components. A blog post with a like button only hydrates the like button island — the 1200-word article text, the header, and the footer generate zero JavaScript execution on the client.

Each island has its own isolated state. Islands cannot share React state directly because they are separate React trees. This is by design: if two components need to share state, they should be merged into a single island. Cross-island communication uses URL params, DOM events, or lightweight state libraries.

Sites migrated from React SPA to Islands Architecture (like the Astro documentation site) report dramatic improvements: JavaScript payloads drop by 70-90%, TTI improves by 2-4 seconds on mobile, and Lighthouse performance scores jump from 60s to 90s+. The gains are most pronounced on content-heavy pages.

Which Astro hydration directive hydrates a component only when it scrolls into the viewport?

Islands Architecture keeps most of the page as static HTML and hydrates only isolated interactive components. Astro provides hydration directives: client:load (immediate), client:idle (after idle), client:visible (on scroll), and client:only (client-only render). Each island is independently hydrated, making JavaScript proportional to interactivity rather than page size.