Astro JS - Islands Architecture

Quiz

Islands Architecture

The Astro framework popularized a new frontend architecture called island architecture. In this architecture, the majority of pages are loaded with static HTML with smaller islands of JavaScript that are lazily loaded when the user scrolls to them. This architecture reduces the JavaScript load of websites and improves loading speed. In this chapter, we will learn all about the island architecture in Astro JS.

What is an Astro Island?

In Astro framework, an island is an enhanced interactive UI component inside a static HTML page that can be hydrated on demand at client-side. The island reduces the JavaScript load at client-side and improves loading speed. Here is how island architecture works in Astro JS.

How Islands Architecture Works?

An Astro island can be defined using any frontend framework like React, Vue, Svelte, etc.
Then the island will be imported to an Astro page based on hydration strategies.
The Astro page will be rendered with static HTML, and the island will be hydrated on demand at client-side.

Example of Astro Islands Architecture

In the section below, we will create a simple Astro island using React js.

Step 1: Create a React Component

The code below, create a counter React component at 'src/' directory. The component will have a button that will increase the count by 1. This counter component will in an island of Astro page.

// File: src/components/Counter.jsx

import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
        Count: {count}
    </button>
  );
}

Step 2: Use the Component in Astro Page

The code below defines an Astro page at 'src/pages/index.astro'. The page imports the Counter component and renders it in the page. The Counter component loads JavaScript only when needed using the 'client:load' directive.

<!-- File: src/pages/index.astro -->

---
    import Welcome from '../components/Welcome.astro';
    import Layout from '../layouts/Layout.astro';
    import Counter from "../components/Counter.jsx";
---

<Layout>
    <Welcome />
    <h1>Welcome to Astro</h1>
    <p>This content is static.</p>
    
    <!-- Interactive Island -->
    <Counter client:visible />
</Layout>

Step 3: Output

In the output image below, you can see that we successfully setup the island in Astro page. The island component will be loaded when user scrolls to it. We verified this by visiting browser dev tools.

Island Hydration Strategies

In the above example, we used the 'client:visible' directive to load the island component. This will ensures that the island is loaded when the component is visible on the viewport. However, there are other hydration strategies available in Astro JS. Let see all of them below.

Directive	Behavior	Use Case
client:load	Hydrates immediately after page load.	For components that must be interactive as soon as possible.
client:idle	Hydrates when the browser is idle.	For non-critical components (e.g., sidebar, animations).
client:visible	Hydrates when the component enters the viewport.	For lazy-loading interactive elements (e.g., chat widgets, carousels).
client:only	Fully runs on the client (not included in static HTML).	For components that don't need SSR (e.g., real-time widgets).

Example of Island Hydration Strategies

The code below, shows how to use the different hydration strategies in Astro island. Here,

The 'client:only' directive is used to load the weather widget component, which does not need SSR. This is because the weather data is fetched from an API and does not change frequently.
The 'client:idle' directive is used to load the chat widget component, which is not critical and can be loaded when the browser is idle.
The 'client:visible' directive is used to load the notification bell component, which is interactive and should be loaded when the user scrolls to it.

---
    import ChatWidget from "../components/ChatWidget.jsx";
    import NotificationBell from "../components/NotificationBell.jsx";
    import WeatherWidget from "../components/WeatherWidget.jsx";
---

<html>
    <body>
        <h1>Astro Hydration Examples</h1>

        <!-- Hydrates immediately -->
        <NotificationBell client:load />

        <!-- Hydrates when the page is idle -->
        <ChatWidget client:idle />

        <!-- Hydrates only when visible -->
        <WeatherWidget client:visible />
    </body>
</html>

Drawbacks of Island Architecture

Even though the island architecture is a great way to load JavaScript on webpages, there are some drawbacks to this architecture. Here are the main drawbacks of island architecture.

The island architecture is not ideal for highly interactive applications like online tools, dashboards, etc. This may require full JavaScript control over the page.
Not suitable for real time applications, where the user needs to see the latest data immediately.
It works well only for static content, such as blogs, documentation, and e-commerce sites.

Print Page