Islands and client directives in Astro

This chapter follows Content collections in Astro.

What is Astro introduced islands as interactive components in a static page. This chapter is the mechanics: how to bring in a UI framework, how to choose when each island loads, and what you give up at the boundary between server and browser.

Add a UI framework

Astro components cover static markup and small scripts. For stateful UI, add a framework integration:

1
npx astro add react

Official integrations exist for React, Preact, Svelte, Vue, Solid, and Alpine.js. Several can coexist in one project, although each one adds its own runtime to the pages that use it.

1
import { useState } from 'react';
2

3
export default function Counter({ start = 0 }: { start?: number }) {
4
  const [count, setCount] = useState(start);
5
  return <button onClick={() => setCount(count + 1)}>Clicked {count} times</button>;
6
}

Import it into an .astro file like any component. Without a directive it renders to HTML on the server, and the button does nothing in the browser.

Client directives

A client:* directive turns the component into an island and sets when it hydrates:

1
---
2
import Counter from '../components/Counter.tsx';
3
import Comments from '../components/Comments.tsx';
4
import MobileNav from '../components/MobileNav.tsx';
5
---
6
<MobileNav client:media="(max-width: 50em)" />
7
<Counter client:load start={5} />
8
<Comments client:visible />

client:only needs the framework name because Astro cannot detect it without rendering. Since there is no server HTML, use a placeholder to avoid layout shift: <Map client:only="react"><p slot="fallback">Loading map…</p></Map>.

Choosing the latest directive that still feels responsive is the main performance decision in an Astro page. The default, no directive, is the cheapest of all.

What crosses the island boundary

Props for an island are serialized into the HTML so the browser can hydrate with the same values. Strings, numbers, booleans, arrays, plain objects, Date, Map, Set, URL, and similar built-ins are supported. Functions are not, so you cannot pass an onClick handler from an .astro file into a React island; define the handler inside the island instead.

Children work. Content passed between a framework component’s tags is rendered on the server and handed to the island as static HTML:

1
<Dialog client:idle>
2
  <p>This paragraph is server-rendered Astro content inside a React island.</p>
3
</Dialog>

Keep island props small. Everything you pass is embedded in the page, and passing a whole content collection to one island undoes the point of shipping less to the browser.

Sharing state between islands

Islands hydrate independently and do not share a React tree, so React context does not connect two islands. Use a small framework-agnostic store instead. Astro’s documentation recommends nanostores:

1
import { atom } from 'nanostores';
2

3
export const cartCount = atom(0);

1
import { useStore } from '@nanostores/react';
2
import { cartCount } from '../stores/cart';
3

4
export default function AddToCart() {
5
  const count = useStore(cartCount);
6
  return <button onClick={() => cartCount.set(count + 1)}>Add ({count})</button>;
7
}

Any island that reads cartCount, in any framework, updates when it changes. Custom DOM events and URL state work too when you want no dependency at all.

Server islands

A server island is the server-side counterpart: a component that renders on the server after the page, so a cached or static page can still contain a per-visitor fragment such as an avatar, a cart total, or a price.

1
---
2
import UserMenu from '../components/UserMenu.astro';
3
---
4
<UserMenu server:defer>
5
  <span slot="fallback">Sign in</span>
6
</UserMenu>

The page is served immediately with the fallback. A small script then requests the island from the server and swaps it in. Inside UserMenu.astro, Astro.cookies and the request are available as in any on-demand route. Server islands need an adapter, since something has to answer that follow-up request (Server rendering in Astro).

Client-side navigation with view transitions

By default every link is a full page load. Adding <ClientRouter /> to a layout’s <head> makes Astro intercept same-site navigation, fetch the next page, and swap it in with an animated transition:

1
---
2
import { ClientRouter } from 'astro:transitions';
3
---
4
<html lang="en">
5
  <head>
6
    <ClientRouter />
7
  </head>
8
  <body>
9
    <slot />
10
  </body>
11
</html>

Name elements with transition:name to morph them between pages, and keep an island alive across navigation, such as a playing audio player, with transition:persist. Scripts that set up the page should listen for the astro:page-load event, because a bundled script runs only once, not after every client-side navigation. Browsers that support cross-document view transitions can also animate plain multi-page navigation with CSS alone, without the router.

Next: Server rendering in Astro.