Astro Islands

Astro renders components to HTML and sends no client JavaScript by default. Use an island only for the part that needs independent behavior.

• A client island adds browser interactivity.
• A server island defers slow or personalized server content.

Add a client island

Install the Astro React integration:

npx astro add react

Create src/components/Counter.tsx:

import { useState } from 'react';

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

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

Add the component to an Astro page with a client directive:

---
import Counter from '@/components/Counter';
---

<Counter client:visible />

client:visible loads the island JavaScript when the component enters the viewport.

Choose the least eager directive that gives the required experience:

For small DOM behavior, use a normal <script> in an Astro component. A UI framework is not necessary for one local event listener.

Read the Astro guide for client islands and all client directives.

Add a server island

Create src/components/AccountSummary.astro:

---
await Astro.locals.loadAuthSession();
const user = Astro.locals.user;
---

<p>{user ? `Signed in as ${user.email}` : 'Not signed in'}</p>

Add the component to a page:

---
import AccountSummary from '@/components/AccountSummary.astro';
---

<AccountSummary server:defer>
  <p slot="fallback">Loading account...</p>
</AccountSummary>

Astro sends the main page first. It then requests the server island from a generated route.

If slow or personalized content must not delay the page, use a server island. Each island adds a Worker request.

Do not split every panel into a server island. Extra requests and repeated database queries can make the page slower and more expensive.

Read the Astro guide for server islands.