Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Components and Islands

Islands Architecture in Astro

Understand Astro islands and partial hydration: static HTML around interactive components, framework components, hydration cost and server islands.

Most web pages are mostly static. A news article is text and pictures with maybe a comment box, a share button and a newsletter form. Rendering the entire page as a JavaScript application just to power those few interactive bits is wasteful. Islands architecture takes the opposite approach: the page is static HTML, and only the interactive parts, the islands, are turned on with JavaScript.

The idea

Imagine the page as an ocean of fixed HTML with small islands of interactivity:

Ocean and islands

Static HTML Header, article, footer
Island: search Loads its own code
1 / 2

Hydration is the step where the browser takes server-rendered HTML and attaches JavaScript behaviour to it. A normal single-page app hydrates everything. In Astro, only the islands hydrate. The rest of the page never receives JavaScript at all.

The benefits:

  • Less JavaScript, so faster downloads and less main-thread work.
  • Independent loading: a heavy carousel does not delay the search box.
  • Resilience: if one island fails, the surrounding page still works.

Using a framework component

Suppose you installed React with npx astro add react and wrote src/components/Counter.jsx. In an .astro page you import it like any other component:

ASTRO
---
import Counter from "../components/Counter.jsx";
---
<h1>Static heading</h1>
<p>This paragraph is plain HTML.</p>

<Counter />

Without further instructions, Astro renders the component to HTML on the server and ships no JavaScript for it. The counter appears but its button does nothing. To make it an island you add a client:* directive:

ASTRO
<Counter client:load />

Now Astro sends the component's code (and the React runtime) and hydrates it as soon as the page loads. The next lesson, Client directives, covers all the options.

What the HTML looks like

An island is wrapped in a custom element named astro-island. The attributes describe which component to load, which props to pass and when to hydrate. You do not write this yourself; it is what the page looks like in "view source":

HTML
<h1>Static heading</h1>
<p>This paragraph is plain HTML.</p>
<astro-island
  uid="Z1xYz"
  component-url="/_astro/Counter.abc123.js"
  component-export="default"
  renderer-url="/_astro/client.def456.js"
  props="{&quot;start&quot;:[0,5]}"
  client="load"
  opts="{&quot;name&quot;:&quot;Counter&quot;,&quot;value&quot;:true}"
  ssr>
  <button>Count: 5</button>
</astro-island>

The inner <button> is the server-rendered HTML, so it appears before any JavaScript downloads. The astro-island element is what the small Astro runtime uses to decide when to load the code.

Props must be serializable

Props travel from the server to the browser inside the props attribute, so they must be serializable. Plain objects, arrays, strings, numbers, booleans, Date, Map, Set, URL and BigInt work. Functions cannot be passed to an island from an .astro file, because there is no way to send code through HTML. Pass data in, and let the component define its own handlers.

ASTRO
<!-- fine -->
<Counter client:load start={5} labels={["Add", "Reset"]} />

<!-- not fine: functions cannot cross to the browser -->
<Counter client:load onChange={() => console.log("hi")} />

Children (slots) given to an island are rendered as static HTML on the server and passed in. This lets you nest static content inside an interactive wrapper, such as an accordion whose panels contain plain markup.

Server islands

Astro 5 added server islands for the opposite case: a mostly static page with one piece of dynamic, personalized content (a user avatar, a price, a recommendation). You mark a component with server:defer:

ASTRO
<Avatar server:defer>
  <div slot="fallback">Loading profile...</div>
</Avatar>

The page is served from a CDN as static HTML immediately. The browser then requests the island's HTML from the server and swaps it in. The fallback shows meanwhile. This needs an adapter because the island is rendered on demand; we return to it in the SSR chapter.

How much JavaScript do you save?

Consider a product page with a gallery, a buy button, a header, a footer and 20 paragraphs of text. A full app might hydrate all 25 components. With islands you hydrate two: the gallery and the buy button. Every static component is just HTML.

Stand-in: hydrating only islands

This stand-in renders a page as a list of components. Components flagged as islands get a bundle size; static ones cost nothing. It compares a "hydrate everything" page with an islands page.

Node.js Stand-in: JavaScript cost of islands

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: rendering an astro-island wrapper

The next stand-in produces the same kind of HTML an island leaves behind: server-rendered markup inside a wrapper element that records which component, props and strategy to use. A tiny "runtime" then reads that markup.

Node.js Stand-in: an island wrapper and its runtime

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

When islands are not the answer

If nearly every part of the page shares live state (a spreadsheet, a chat app), splitting it into islands creates more coordination work than it saves. In that case use a single large island, or consider an application framework. Islands shine on pages that are mostly content.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Astro do with a React component that has no client directive?

    Without a client:* directive a framework component is only rendered on the server.
  2. 2. Which props can be passed to an island?

    Props are serialized into the HTML, so functions and DOM objects cannot be passed.
  3. 3. What is hydration?

    Hydration makes already-rendered HTML interactive by running the component code in the browser.
  4. 4. What is a server island (server:defer) for?

    Server islands keep the page cacheable while personalized parts load from the server after the first paint.

Summary

  • Islands architecture serves static HTML and hydrates only the interactive components.
  • Framework components render to HTML only until you add a client:* directive.
  • Islands are wrapped in an astro-island element that carries component, props and strategy.
  • Props must be serializable; functions cannot cross from server to browser.
  • Server islands (server:defer) add dynamic, personalized pieces to otherwise cacheable pages.

Next: Client Directives