Which parts of a static page should become JavaScript islands?

Islands architecture serves most of a page as server-rendered HTML and hydrates only the components that need interaction or personalization. Etsy’s Katie Sylor-Miller coined “component island” in 2019; Jason Miller expanded and documented the idea in a 2020 post. Astro islands documentation, Jason Miller’s original post

Decide what to split

  • 1. Keep content and navigation meaningful in HTML without JavaScript. An article body, heading, and ordinary links should be readable in the initial document.
  • 2. Make only browser-dependent widgets islands. Search autocomplete may need interaction; a static table of contents or author biography often does not.
  • 3. Choose when each widget loads. In Astro, client:load hydrates at page load, client:idle when the browser is idle, and client:visible when the component enters the viewport. Do not give a critical purchase or navigation control the same priority as a lower-page secondary widget by default.
  • 4. Check how separate islands share data. Components may still need common login or cart state; more islands can mean more bundles, communication, and state coordination.

Example: article page with a comment panel

Suppose a long article is delivered as static HTML, while its comment input and sorting controls are interactive. The article should remain readable before scripts load. A comment widget below the fold could use a directive such as client:visible, but check accessibility, discoverability, and how comments are displayed. Measure response bytes, JavaScript execution, and interaction delay on the actual page before deciding that the split helped.

SSG and performance are separate decisions

Static site generation (SSG) creates HTML at build time; islands describe how browser interactivity is divided within that page. They can be combined, but they are not the same mechanism. The amount of HTML, images, CSS, widget code, and server-side personalization all affect performance. Islands do not automatically guarantee a faster score or better accessibility. Test keyboard and screen-reader behavior, and check what remains usable with JavaScript disabled.

Sources