Astro Islands Architecture: Selective Hydration Guide

Stop bloating your frontend. Learn how to use Astro's Islands Architecture to selectively hydrate components and reduce Total Blocking Time.

The Cost of Full Hydration

Modern web frameworks often force a "binary choice": either a page is entirely static and lifeless, or it is a heavy Single Page Application (SPA) that hydrates every single element on the screen. This process, known as hydration—where client-side JavaScript attaches event listeners to server-rendered HTML—often creates a performance bottleneck. Even if only a small search bar needs to be interactive, the browser may still download and execute JavaScript for the entire page layout, increasing Total Blocking Time (TBT).

Astro solves this by treating interactivity as an opt-in feature rather than a default. By using Islands Architecture, Astro renders the majority of your page as static HTML and only "hydrates" specific, isolated components (the islands) that actually require JavaScript.

Selecting the Right Hydration Directive

In Astro, components are server-rendered by default. To make a component interactive on the client, you must use a client:* directive. Choosing the wrong directive can either break your UI or accidentally bloat your bundle.

Immediate Interactivity: client:load

Use client:load for critical UI elements that must be functional the moment the page appears, such as navigation menus or search bars. This tells Astro to prioritize the JavaScript for this component during the initial page load.

Deferred Interactivity: client:visible

For components located further down the page—like a footer newsletter signup or a complex data table—client:visible is the most efficient choice. It utilizes the browser's Intersection Observer API to delay the download and execution of the component's JavaScript until the element actually enters the user's viewport.

Browser-Only Logic: client:only

Some components rely on browser-specific APIs like window, document, or localStorage. Since Astro attempts to render components on the server first, these APIs will throw errors during the build process. client:only skips server-side rendering entirely, rendering the component exclusively on the client.

Practical Example: A Mixed-Framework Page

One of the strongest engineering advantages of islands is framework agnosticism. You can use a React component for a complex state-driven form and a Svelte component for a lightweight animation on the same page without them interfering with one another.

-- src/pages/index.astro
---
import Header from '../components/Header.jsx'; // React
import Footer from '../components/Footer.svelte'; // Svelte
import HeavyChart from '../components/HeavyChart.jsx'; // React
---

<html>
  <body>
    <!-- Hydrate immediately for navigation -->
    <Header client:load />

    <main>
      <p>This text is pure HTML and costs 0 bytes of JS.</p&
      
      <!-- Only load JS when the user scrolls to the chart -->
      <HeavyChart client:visible />
    </main>

    <!-- Hydrate only when visible in the footer -->
    <Footer client:visible />
  </body>
</html>

The State Management Trade-off

Because islands are isolated, they do not share a common framework root. You cannot wrap your entire Astro page in a React Context Provider or a Vue Store because the "gaps" between the islands are static HTML, not framework-managed components.

If you need to share state between two separate islands (e.g., a "Add to Cart" button in a React island updating a "Cart Count" in a Svelte island), you must use an external, framework-agnostic state manager. Nano Stores is the recommended approach for Astro, as it provides a tiny, subscription-based store that can be read by any framework.

Verifying Your Implementation

To ensure your islands are behaving as expected, use these diagnostic steps:

Check the Source: View the page source in your browser. Components without a client:* directive should appear as standard HTML with no accompanying <script> tags for that specific component.
Network Monitoring: Open Chrome DevTools > Network tab. Filter by JS. Scroll down to a client:visible component; you should see the JavaScript bundle for that component trigger only when the element enters the viewport.
Console Audit: If a component using client:only is missing a directive, you will typically see ReferenceError: window is not defined during the build or server-render phase.

Optimizing Interactivity with Astro's Islands Architecture