Islands architecture

On this page 7

Islands architecture is a rendering pattern for web applications in which the server delivers a page as static HTML and only small, independent interactive regions, called islands, are hydrated with JavaScript in the browser. The rest of the page stays as plain markup that never needs a client-side framework runtime.

The pattern targets content-heavy sites that need some interactivity but not a full single-page application. By shipping JavaScript only where it is needed, it reduces download size, main-thread work and the time until the page responds to input.

How islands architecture renders a page

In islands architecture, the page is rendered on the server or at build time into complete HTML, including the initial markup of interactive components. Each interactive component is marked as an island and receives its own small script bundle and serialized props. The browser displays the HTML immediately, then hydrates each island separately.

The defining property is independent hydration. In classic server-side rendering with full hydration, a single root component takes over the whole document, so the framework must download and execute code for every component, even static headers and article text. With islands, static regions are never hydrated, and each island boots without waiting for the others.

The following table lists the building blocks that implementations share.

ElementRoleTypical form
Static shellCarries layout and contentServer-rendered or prebuilt HTML
Island componentProvides interactivity in one regionFramework component with its own bundle
Serialized propsPasses data to the islandJSON embedded next to the markup
Hydration directiveDecides when an island bootsLoad, idle, visible or media query
Island loaderFetches and starts island codeSmall runtime or custom element
Core elements of an islands implementation

Hydration strategies for individual islands

Because islands hydrate separately, each one can use its own hydration timing. This is a practical form of progressive or partial hydration: urgent controls start immediately, while components far below the fold wait until the user scrolls to them.

TriggerWhen code runsSuitable for
On loadAs soon as the page loadsNavigation menus, search boxes
On idleWhen the main thread is idleSecondary widgets, chat buttons
On visibleWhen the island enters the viewportCarousels, comment sections
On media queryWhen a viewport condition matchesMobile-only drawers
Client onlyRendered entirely in the browserComponents that need browser APIs
Common hydration triggers and their uses

Choosing triggers well matters for Interaction to Next Paint. An island that hydrates late may ignore early clicks, so critical controls should hydrate eagerly, and any island deferred to idle or visibility should still look and behave sensibly as plain HTML until it boots.

Islands compared with other rendering models

Islands architecture sits between a multi-page application with plain HTML and a single-page application driven entirely by JavaScript. It keeps server rendering and static generation for content while adding framework components selectively.

ApproachJavaScript shippedNavigation modelBest fit
Islands architectureOnly for interactive regionsFull page loads by defaultContent sites with some widgets
SPA with client-side renderingEntire applicationClient-side routingHighly interactive applications
SSR with full hydrationEntire component treeUsually client-side routingApps needing fast first render
SSG without islandsLittle or noneFull page loadsPurely static documentation
Server componentsOnly client componentsFramework-managed routingLarge React applications
Islands architecture and related rendering approaches

Islands and React Server Components share the goal of keeping non-interactive code on the server, but they differ in structure. Islands are isolated roots chosen at page level, while server components form one tree in which client components are nested and coordinated by the framework router.

Frameworks and practical adoption

The term was popularized in frontend discussions around 2019 and 2020, and several frameworks now build on it. Astro is the best-known implementation and lets islands be written in React, Vue.js, Svelte or other libraries on the same page. Fresh for Deno, Eleventy with partial hydration plugins and Qwik-adjacent tooling use related ideas.

Adoption decisions depend on how much of a page is genuinely interactive. A useful rule is to consider islands when most of the page is content and interactivity is limited to discrete components.

SituationRecommendationReason
Blog, docs, marketing siteStrong candidateMostly static with few widgets
E-commerce product pagesGood candidateStatic details plus cart and gallery
Dashboard or editorUsually unsuitableMost of the screen is interactive
Heavy shared client stateUse with cautionIslands do not share a component tree
Need for app-like transitionsCombine with view transitionsDefault navigation reloads pages
Deciding whether islands fit a project

Limitations and design pitfalls

The main limitation is state sharing between islands. Since each island is a separate root, communication requires a shared store, custom events or URL state, which adds design work that a single component tree would handle implicitly.

  • Too many small islands multiply loader overhead and duplicate framework runtimes when mixed libraries are used.
  • Oversized islands that wrap most of the page recreate full hydration and lose the benefit.
  • Late hydration of key controls produces unresponsive buttons and poor INP.
  • Full page navigation discards island state unless persistence or view transitions are configured.

Measured results vary widely. Sites migrating from full hydration often report large reductions in shipped JavaScript, but the actual gain depends on how much of the original bundle served static content and on whether islands are kept small and well bounded.

A plain-language summary

Most of a typical web page is just text and pictures that never change once they appear. Islands architecture sends that part as finished, ready-to-read content and adds interactive code only to the few pieces that need it, such as a search box or a photo slider.

Picture a printed brochure with a few small electronic buttons glued onto it. The paper does not need batteries, only the buttons do. The result is pages that appear quickly and respond sooner, especially on slower phones.

An example from practice

A software company runs a documentation site with about 1,200 pages. The previous version, built as server-rendered pages with full hydration, shipped roughly 240 KB of compressed JavaScript per page, although interactivity was limited to a search dialog, a theme switch and code-copy buttons.

The team rebuilds the site with an islands-based framework. Articles are generated as static HTML, the search dialog hydrates on load, the theme switch hydrates on idle and an interactive API playground hydrates only when visible. Typical article pages now ship under 30 KB of JavaScript.

Field monitoring after the release shows lower Total Blocking Time and improved INP on mid-range mobile devices, while content and search behave as before. The outcome is faster, lighter pages without losing the interactive features readers relied on.