Islands

An island is an interactive Preact component inside an otherwise static page. Neutron emits the island runtime and component chunk without hydrating the surrounding route.

Add an island

import { Island } from "@neutron-build/core/client";
import Counter from "../components/Counter";

export default function Page() {
  return (
    <main>
      <h1>Static content</h1>
      <Island component={Counter} client="visible" initialCount={0} />
    </main>
  );
}

Props are serialized into the generated HTML, so pass values that can be represented as JSON.

Hydration timing

| Value | Hydration begins | | --- | --- | | client="load" | When the island runtime starts | | client="visible" | When the element enters the viewport | | client="idle" | During browser idle time, with a timeout fallback | | client="media" | When the query passed through media matches | | client="only" | Immediately, rendering a fresh tree if no server markup exists |

For a media-controlled island:

<Island
  component={MobileMenu}
  client="media"
  media="(max-width: 720px)"
/>

Use app mode instead when navigation state, loaders, and actions belong to the whole route rather than a few isolated controls.