What Are Astro Islands? A Plain-English Explanation

Read anything about Astro and you’ll hit the word “islands” within a minute. It’s the idea behind why Astro sites are fast. It’s simpler than it sounds.

The picture

Think of a web page as the sea. Most of the sea is calm. It’s plain words, pictures and links. None of that needs JavaScript, the code that makes things move. So Astro sends none.

Here and there, something needs to react to the visitor. A search box. A slideshow. A “buy” button. Each of those is an island. It’s a small patch of the page with its own JavaScript, sitting in a sea of plain page that has none.

That’s the whole idea. JavaScript only where you need it, instead of everywhere.

Why it matters

Many web tools send JavaScript for the whole page. Then the visitor’s browser has to run it all before the page is ready. On a slow phone, you feel the wait.

Astro does the opposite. The page arrives finished. Only the islands load extra code. The rest is ready the moment it arrives.

What we saw when we built one

We built a test page with a plain greeting and four counter buttons. Each button was marked as an island in a different way. Here’s what Astro made:

• The greeting, with no island mark, came out as plain HTML: <p>Hello, Sam!</p>. No JavaScript at all.
• Each counter became an <astro-island> tag, with a note about when to wake it up.
• A page with no islands, like our about page, loaded no island code at all.

The counter’s own code was tiny. The React tool it needed was about 207 KB. That’s the real cost of an island, and it’s why you only pay it where it matters.

How you make an island

A component becomes an island when you add a mark called a client directive:

---
import Counter from '../components/Counter.jsx';
---
<Counter client:load />

Without client:load, the same component is drawn once and arrives as plain HTML. With it, Astro also sends its JavaScript and wakes it up in the browser.

The mark also says when to wake it up. client:load means right away. client:visible means when it scrolls into view. There are five, and client directives explained tells you which to use.

You don’t always need a framework

Islands can be made with React, Vue, Svelte and others. Our tutorial on adding a React component builds your first one.

But for a menu button or a copy button, a plain <script> in an Astro file is often better. It costs almost nothing. We explain when in do you need React with Astro?

Server islands

There’s a second kind. A server island is a part of the page made fresh on the server when someone visits, while the rest was made ahead of time. It’s for things like “Welcome back, Sam” on a page that otherwise never changes. See how to use server islands.

The rule of thumb

Build everything as a plain page first. Turn a piece into an island only when it has to react to the visitor. Your site will be fast without trying, and the islands you add will earn their cost.

Frequently asked questions

Do I need islands to use Astro?

No. Most pages on most Astro sites have no islands at all. Islands are only for parts that react to the visitor, like a search box or a shopping cart.

Do islands need React?

No. An island can be made with React, Preact, Vue, Svelte or SolidJS. For small things, a plain script in an Astro file is often enough.

Are islands the same as components?

Every island is a component, but most components are not islands. A component becomes an island only when you add a client directive to it.