Islands and partial hydration

The problem: paying for a whole app to read an article

Picture a news article page: a header with a menu, a headline, a photo, 1,500 words of text, share buttons, a newsletter signup, comments, and a footer. Most of the page is words and pictures. Only four small parts react to the reader.

The team built the site with a popular framework and server-side rendering (SSR), so the HTML arrives complete and the text shows quickly. Then the page downloads 420 KB of compressed JavaScript. That bundle holds the framework, the router, every component on the page, and the data used to render them, sent a second time as JSON.

420 KB compressed is about 1.5 MB once unzipped, and a mid-range Android phone gets through roughly 1 MB of JavaScript per second of main-thread work (the rule of thumb from the estimation lesson). So the browser spends about 1.5 seconds parsing and running that code, after about two seconds of download on a slow 4G link. Meanwhile the reader taps the menu button and nothing happens. And the headline, the paragraphs, and the footer never needed JavaScript at all.

Why the whole page pays: a quick recap of hydration

Hydration is the step where the framework, running in the browser, walks the server-made HTML, rebuilds its component tree in memory, and attaches event listeners. The key fact: classic hydration works on the whole tree. To attach one handler to the menu button, the framework runs every component, because it cannot know which parts are static without running them.

• Download cost. Every component's code ships, including the many that only print text.
• Data cost. Props for every component ship again as serialized JSON, so the article's text travels twice: once as HTML, once as JSON.
• CPU cost. The framework runs every component in the browser to match it with the existing HTML.
• Waiting cost. Until the whole tree finishes, no part of it responds. A tap during hydration is lost or delayed.

The idea in one sentence

What if the page shipped as plain HTML, and only the four interactive parts got JavaScript, each loaded on its own and started at the moment it is needed? That is the islands architecture, built on partial hydration: hydrating only some parts of a page. A related idea, resumability, tries to skip hydration entirely. This lesson covers both, and what each saves.

The mental model: a static sea with islands

Think of the page as a sea of plain HTML. The sea is made once, on the server or at build time, and it never needs JavaScript. Dotted across it are a few islands: small, self-contained interactive components.

Each island has its own little bundle and starts up on its own. An island knows nothing about the sea around it, and usually nothing about the other islands.

Where the name comes from

Katie Sylor-Miller, then a frontend architect at Etsy, coined the term "component islands" during a 2019 meeting with Jason Miller. In August 2020 Jason Miller, the creator of Preact, wrote the post "Islands Architecture", which gave the pattern its widely used name and description. Server pages with a sprinkle of jQuery were islands in spirit; what was new was doing it with modern components that render on the server and, only where needed, run again in the browser.

Three properties that define an island

1. It is its own root. Each island is mounted separately, with its own small component tree. A crash in one island does not take down the others.
2. It is server rendered first. The island's HTML is already in the page, so the reader sees a real button, a real form, real comment text, before any JavaScript runs.
3. It loads on its own schedule. Each island chooses when to load: right away, when the browser is idle, when it scrolls into view, or when a media query matches. Some never load at all.

What it is not

Islands are not code splitting. Code splitting cuts one app's bundle into chunks, but the app is still one tree and still hydrates as a whole (or at least from its root down). Islands remove the single tree: the static parts have no client code at all, not even lazily loaded code.

Islands are not a client-side app either. Navigation is usually a normal full page load (a multi-page app, or MPA), not a client-side router; the spa-vs-mpa lesson covers that trade-off.

How islands work, step by step

Astro is the best-known islands framework, so we will follow one article page through it. The same steps apply, with different names, in Fresh, Eleventy's is-land, and others. Here is the page. Every component is rendered on the server; only the three with a client: directive become islands.

---
// src/pages/blog/[slug].astro (Astro)
import Header from "../../components/Header.astro";
import MenuButton from "../../components/MenuButton.tsx";
import ShareBar from "../../components/ShareBar.tsx";
import Comments from "../../components/Comments.tsx";
import Footer from "../../components/Footer.astro";
const post = await getPost(Astro.params.slug);
---
<Header>
  <MenuButton client:load />
</Header>
<article>
  <h1>{post.title}</h1>
  <Fragment set:html={post.html} />
</article>
<ShareBar client:idle url={post.url} />
<Comments client:visible postId={post.id} />
<Footer />

One detail surprises people: a React component used without a client: directive is still rendered, but only to HTML. Its code never reaches the browser. The directive, not the component's framework, decides whether something is an island.

The six steps

1. Render everything to HTML. At build time or per request, Astro runs every component on the server, including the React ones.
2. Wrap each island. Around each component with a directive, Astro writes a wrapper element, astro-island. Its attributes record where the component's code lives, where the framework's client renderer lives, the props (serialized as JSON), and the directive.
3. Bundle per island. The bundler builds one small entry chunk per island component. Code shared between islands, like react-dom, goes into a shared chunk that is downloaded once, however many islands use it.
4. Paint the HTML. The browser paints the page like any static page; buttons and comments are already real HTML. A tiny inline script defines the astro-island element.
5. Wait for the trigger. As each astro-island element connects, it reads its directive. load starts at once; idle waits for requestIdleCallback; visible sets up an IntersectionObserver; media checks matchMedia.
6. Hydrate that island alone. When the trigger fires, the element imports the renderer and the component chunk with a dynamic import(), parses its props, and hydrates its own subtree (for React, a hydrateRoot call on that element). Nothing outside it is touched.

What the HTML looks like

The exact attributes change between Astro versions, so treat this as a simplified picture. Everything needed to wake an island later is written into the HTML now.

<astro-island
  uid="Z1abc"
  component-url="/_astro/Comments.B7x2.js"
  renderer-url="/_astro/client.Dk91.js"
  props='{"postId":[0,"p_812"]}'
  client="visible"
  ssr>
  <section class="comments">
    <h2>42 comments</h2>
    <ul><li>Great article...</li></ul>
    <button>Load more</button>
  </section>
</astro-island>

Static children inside an island

An island can wrap static content. If you write MenuButton client:load with a list of links inside it, Astro renders those links on the server and passes them into the island as ready-made HTML (Astro calls this a slot). The links' components do not ship. This lets a small interactive shell, like a collapsible panel, hold a large amount of static content without paying for it.

Props are the opposite. Whatever you pass to an island as props is serialized into the HTML and parsed in the browser. Passing a 200-item array to an island that only shows the first five puts all 200 into the page. Props must also be serializable: you cannot pass a function from the server page to an island, because there is no way to write a function into HTML and revive it in the browser.

Choosing when each island wakes: the client directives

The directive answers one question per island: when is it worth spending its bytes and CPU? Astro gives five answers; other tools use similar ones (Eleventy's is-land has on:visible and on:idle).

client:load: as soon as possible

The island's code starts downloading right after the page loads, and it hydrates as soon as the code arrives. Use it for controls the reader is likely to touch in the first seconds and that sit above the fold: a menu button, a search box in the header, a cookie banner's buttons.

The mistake: putting client:load on everything "to be safe". Then every island competes for the network and the main thread at the same moment, and you are back to full hydration with extra steps.

client:idle: when the browser has a free moment

The island waits until the page has finished loading and the browser reports idle time through requestIdleCallback (in browsers without it, Astro waits for the load event instead). Since Astro 4.15 you can pass a timeout, as in client:idle={{ timeout: 500 }}, to cap the wait. Use it for things that should work soon but not first: a share bar, a "like" button, a newsletter box near the top.

The mistake: assuming idle comes quickly. On a busy page on a slow phone, the first idle moment can be seconds away. A control the reader reaches for in the first two seconds should not wait for idle.

client:visible: when it scrolls into view

The island sets up an IntersectionObserver and loads only when its element enters the viewport. Since Astro 4.1 it accepts a rootMargin option, as in client:visible={{ rootMargin: "200px" }}, so it can start a little before it is visible. Use it for anything below the fold: comments, a related-posts carousel, a map, an embedded video player. If the reader never scrolls there, the code is never downloaded.

The mistake: using it for something big and important that the reader reaches quickly. The reader scrolls, sees the comments, taps "Reply", and the 45 KB comments chunk has only just started downloading. Starting early with a rootMargin, or keeping the island small, avoids the gap.

client:media: only when a media query matches

The island loads only if a CSS media query matches, for example client:media="(max-width: 50em)". Use it for parts that only need JavaScript on some screens: a hamburger menu that exists only on mobile, a sidebar filter that becomes a drawer on small screens. On desktop the code is never fetched.

The mistake: hiding the element with CSS on the other screens but forgetting that its server HTML is still there. If the desktop layout shows a different version of the menu, make sure the mobile version is hidden there, or readers of assistive technology may meet two menus.

client:only: skip the server, render in the browser

The component is not rendered on the server at all. The page gets an empty slot, and the component renders from scratch when its code loads, as in client-side rendering. You must name the framework, like client:only="react". Use it for components that cannot run on a server, such as ones that read window or localStorage during render.

The mistake: using it for content. The content is missing from the HTML, so it shows late, may shift the layout when it appears, and is not in the page that search engines and link previews read. Astro lets you pass a fallback (an element with slot="fallback") to reserve the space.

No directive, and server islands

No directive means plain HTML: the default, and the cheapest choice. Astro 5 also added server islands with server:defer: a part of the page, like a personalized "Hi, Maya" box, is rendered on the server in a separate request after the main page, so the main page can be cached on a CDN while the personal part is filled in. It echoes Partial Prerendering from the streaming SSR lesson, with one difference: Partial Prerendering streams the dynamic holes into the same response, while a server island is fetched with its own request.

Partial, progressive, selective: untangling the words

Several terms sound alike and get mixed up, in blog posts and in interviews. They answer different questions. Getting them straight is a quick way to show you understand the topic.

Two questions: which parts, and when

• Partial hydration answers "which parts?": only some components hydrate, and the rest never ship code. Islands are the best-known form. React Server Components are another: server components never ship, client components do.
• Progressive hydration answers "when?": the page still hydrates as one tree, but in pieces over time, ordered by priority or triggered by visibility or interaction, instead of all at once. All the code still ships eventually.
• Selective hydration is React 18's form of progressive hydration. Each Suspense boundary hydrates on its own, and React hydrates the boundary the user is interacting with first. The streaming SSR lesson covers it in depth.
• Lazy hydration is the informal name for the trigger part: hydrate a component on visibility, idle, or first interaction. Astro's directives are lazy hydration applied to islands. Angular's incremental hydration applies it inside one app tree.

So islands are partial and lazy: only some parts ship code, and each part chooses when. Progressive and selective hydration make full hydration smarter about timing but do not remove code: the static article text is still a component in the tree, still downloaded, still run.

Why the difference matters

Timing techniques make the tapped part respond sooner, which helps INP (Interaction to Next Paint, the Core Web Vital for input responsiveness). But total bytes and total CPU stay about the same, just in smaller slices.

Partial hydration cuts the total. If 80 percent of the page is static, 80 percent of the component code never ships and never runs. That is why content sites see large drops in JavaScript when they move to islands, and why apps that are interactive everywhere see little.

Resumability: skipping hydration altogether

Islands reduce how much hydrates. Resumability, the idea behind the Qwik framework (created by Misko Hevery, who earlier created AngularJS), asks a sharper question: why hydrate at all?

The server already ran the components. It knows where every listener is and what every piece of state holds. If it writes that knowledge into the HTML, the browser can resume where the server stopped, instead of running the components again to rediscover it.

What hydration replays

To attach a click handler, a hydrating framework needs two things: which DOM node gets the handler, and the handler function itself, with the state it closes over. Neither is in plain HTML. So the framework calls every component function again in the browser and lines the result up with the DOM. That is the replay: redoing work the server already did, to recover information the server threw away.

Islands shrink the replay to a few components. Resumability tries to remove it. The cost moves from "run components on load" to "write more into the HTML, and fetch small pieces of code when they are needed".

How Qwik resumes

1. The compiler splits code at every $. In Qwik, component$, onClick$, and useTask$ mark boundaries. The Qwik optimizer pulls each marked function into its own tiny chunk with a stable name, so a single click handler can be loaded on its own.
2. The server writes listeners into attributes. A button's HTML carries an attribute like on:click whose value points at a chunk and a symbol inside it. No code is attached; it is just a string.
3. The server writes state into the page. The component state and signals the handlers need are serialized into a JSON script block in the HTML.
4. The browser loads only the Qwikloader. A small script, about 1 KB, adds one listener per event type on the document. Nothing else runs at startup.
5. On the first click, the loader resolves the handler. The event bubbles to the document. The loader walks up from the target, finds the on:click attribute, imports that chunk, restores the state it needs, and calls the handler.

<!-- Simplified Qwik output for a counter -->
<button on:click="q-chunk-a1.js#Counter_onClick_x9">
  Count: <span>3</span>
</button>

<script type="qwik/json">
  { "objs": [3], "subs": [...] }
</script>

<script id="qwikloader">/* about 1 KB: one listener per event type */</script>

The catch: the first interaction

If the handler's code is fetched only on click, the click waits for a round trip: 100 ms or more on mobile. Qwik handles this by prefetching likely chunks in the background after load (using modulepreload hints or a service worker, depending on version), so the code is usually in the cache by the time the user clicks. That means resumable apps still download code; they just do not execute it at startup.

Other costs are real too. Everything a handler closes over must be serializable, so the optimizer can move it to its own chunk; capturing an instance of an arbitrary class, or an object from a third-party library, in an onClick$ closure fails. Serialized state makes the HTML larger, $ boundaries are a new habit, and the component ecosystem is smaller than React's.

How to talk about its performance

Qwik's headline claim is that startup JavaScript stays near constant as the app grows. That follows from the design. Whether a real product is faster overall depends on prefetching, serialized state size, and how much code the first interactions pull in. Treat it as a property of the architecture, and measure INP and total bytes before promising a number.

Sharing state between islands, and what it costs

Islands are independent by design. That is their strength until two of them need to agree on something. The classic case is a shop: an "Add to cart" island in the product area and a cart badge island in the header. Click one, and the other must show the new count.

In a fully hydrated React app, both would sit under one CartProvider context and share state for free. Islands have no common parent, and a provider in the server layout does nothing in the browser, because the layout never hydrates.

Four ways to connect islands

The costs people forget

• The framework runtime ships once per framework, not once per island. Three React islands share one copy of react-dom. But a page with a React island, a Vue island, and a Svelte island ships three runtimes. Mixing frameworks is a migration tool, not a style.
• Shared code becomes shared chunks. A utility library imported by four islands is downloaded once, but it is downloaded as soon as the first of those islands wakes. A heavy shared import can turn a light client:load island into a heavy one.
• Late islands miss early state. An island that hydrates on visible starts with the state in the store at that moment. With events, it misses everything that happened before. Design for "read the current value, then subscribe".

// src/stores/cart.ts: imported by both islands
import { atom } from "nanostores";

export const cartCount = atom(0);

// AddToCart.tsx (React island)
import { useStore } from "@nanostores/react";
import { cartCount } from "../stores/cart";
export function AddToCart() {
  const count = useStore(cartCount);
  return <button onClick={() => cartCount.set(count + 1)}>Add to cart</button>;
}

// CartBadge.svelte reads the same atom with $cartCount

How much JavaScript each approach ships

Numbers make the trade-offs concrete. Take the article page from the first chapter and build it five ways. The sizes below are illustrative but realistic, compressed (gzip or Brotli) as they travel on the wire. To turn them into time we use the two rules of thumb from the estimation lesson: compressed JavaScript is about 3.5 times bigger once unzipped, and a mid-range phone gets through about 1 MB of unzipped JavaScript per second of main-thread work.

The page, priced five ways

• Full hydration: 420 KB, all run at startup: framework 60 KB, router and shell 50 KB, every component 150 KB, shared libraries 100 KB, and the page data again as JSON 60 KB.
• Progressive or selective hydration: still 420 KB. The menu responds sooner, but the total work is the same.
• React islands: 87 KB at startup. React 60 KB, menu 15 KB, share bar 10 KB, loader 2 KB. Comments (45 KB) and signup (15 KB) load only if the reader scrolls to them.
• Preact islands: 32 KB at startup, because the runtime drops to a few KB.
• Resumable (Qwik): about 1 KB runs at startup. Handler chunks are prefetched in the background, but nothing runs until a click.

Two lessons hide in that table. First, the biggest single saving is not loading the static components, which islands and resumability both achieve. Second, once you use islands, the framework runtime becomes the largest line item, which is why islands sites often pick a small framework (Preact, Svelte, Solid) for their islands.

Lab: decide the islands yourself

Below is the same article page with eight components. For each one, choose: static HTML, or an island with a directive. The lab adds up the JavaScript at startup and in total, estimates when each part becomes interactive on a slow phone, and warns you about the classic mistakes: dead buttons, content missing from the HTML, and early code nobody needed. Try to get startup JavaScript under 100 KB with no warnings.

Measuring what you ship

• The Network panel, filtered to JS. Add up the scripts after load, then again after scrolling to the bottom: startup cost and worst case.
• The Coverage panel in Chrome DevTools. It shows how much of each loaded script actually ran. Large unused percentages on a content page point at components that should not be islands.
• Total Blocking Time in Lighthouse for the lab view, and INP from real users for the field view. Islands should lower both. If INP does not move, the slow part is probably one heavy island or a third-party script, not hydration.

Failure modes, edge cases, and accessibility

Islands remove a lot of JavaScript, and with it a lot of bugs. But they add a new kind: the gap between a part of the page that looks ready and a part that is ready. Most failures below come from that gap.

Dead buttons before the island wakes

Server HTML draws a real-looking button long before its island hydrates. If the reader taps it in that window, nothing happens. This is sometimes called the uncanny valley of server rendering, and lazy directives make the window longer. A client:visible menu at the top of the page gains nothing: it is visible at once, so it starts loading at once anyway, just a little later than with client:load.

• Notice it: a high rate of repeated taps on the same control in session recordings, rage-click metrics, or poor INP on first interactions.
• Fix it: use client:load for above-the-fold controls; keep their islands small; and make the HTML work on its own where you can (a menu that is a link to a sitemap page, a form with a real action). Do not count on a tap made before the island woke being replayed later; test it on a throttled phone.

The forgotten directive

The opposite bug: an interactive component used without a directive renders perfectly and never works. It passes a visual review and a screenshot test. Catch it with an end-to-end test that clicks every control, or a lint rule that flags components with event handlers used without a client: directive.

Layout shift and missing content with client:only

A client:only island has no server HTML, so its space is empty until it renders. When it appears, everything below it moves: a Cumulative Layout Shift (CLS) problem. And its content is absent from the HTML that crawlers and link previews read. Reserve its space with CSS or a fallback slot of the right size, and keep content out of client:only islands.

Heavy props and hydration mismatches

Each island hydrates like a tiny SSR app, with the same mismatch risks: a timestamp in the server's time zone or a random id renders differently in the browser. Big props are the other trap: each island's props are serialized into the HTML, and a page with 30 product-card islands each carrying the full product object can ship more JSON than the old full-hydration page did.

Too many islands, or the wrong page for islands

Islands pay off when interactive parts are few and far apart. A search results page where every card has a favorite button, a hover preview, and a compare checkbox becomes 60 islands. At that point one island around the list, or a regular hydrated app, is simpler and often faster.

Navigation is the other edge. Islands sites are usually multi-page: every link is a full page load, and every island starts from scratch. A music player island stops when the reader clicks to the next article. Astro's client router with transition:persist can keep an island alive, but needing a lot of that is a sign you want a single-page app.

Accessibility angles

• Start from semantic HTML. Because the server HTML is what users meet first, it must already be correct: real button and a elements, labels on inputs, headings in order. An island should add behavior, not fix markup.
• State attributes must be right before hydration. A disclosure rendered with aria-expanded="false" that does not respond yet is confusing but honest. One rendered without the attribute, which the island adds later, announces differently before and after.
• Focus must survive hydration. Hydration that reuses the DOM keeps a keyboard user's focus; a client:only island that replaces a placeholder can lose it.
• Live regions belong in the server HTML. A cart badge that announces changes needs its aria-live region present from the start; a region inserted at hydration time may not be announced.

In real products, and in the interview

Who uses which approach

• Astro is islands-first: zero JavaScript by default, with islands in React, Preact, Svelte, Vue, or Solid. It is popular for docs (its Starlight theme), blogs, and marketing sites.
• Fresh, Deno's framework, ships only the Preact components in its islands folder.
• Eleventy offers is-land, a small custom element that wakes its children on triggers like visible, idle, or a media query, around any framework or plain web components.
• Marko, the framework eBay built and uses for its pages, has done automatic partial hydration for years: its compiler works out which components are interactive, so authors do not mark islands by hand.
• Qwik, built at Builder.io, is the main resumable framework, with Qwik City for routing.
• React Server Components (Next.js App Router and others) bring partial hydration into a single React tree. The react-server-components lesson covers them.

Where you do not see islands: Gmail, Figma, Notion, trading dashboards. Almost every pixel is interactive and the user stays for hours, so the startup cost is paid once and amortized. The choosing-rendering lesson walks through those cases.

When to bring it up

Bring islands up when the prompt is content-heavy and reached from search or links: a news site, a blog platform, docs, a product detail page, a landing page. Those prompts usually list SEO and fast first load on mobile as non-functional requirements. That is your cue: "most of this page is static, so I would ship it as HTML and hydrate only the interactive parts".

Do not force it into an app prompt. For a chat app, a spreadsheet, or a dashboard, say why islands do not fit: almost everything is interactive and shares state, so the savings are small and the glue code is large.

What to draw and what to say

1. Draw the page and shade the islands, each labelled with its trigger.
2. Give a number. "Full hydration would ship around 400 KB and keep a mid-range phone busy for about 1.5 s. Islands put about 90 KB on the critical path, about 0.3 s."
3. Name the cost. Shared state across islands (cart badge and add-to-cart via a tiny store plus a cookie), full page navigations, and the dead-button window for lazy islands.
4. Mention the alternatives. Selective hydration for app-like React pages, Server Components for partial hydration in one tree, resumability when startup JavaScript is still the bottleneck.

How deep to go by level