Islands Architecture and Selective Hydration
Islands Architecture describes a web architecture where independent, isolated interactive components (islands) are embedded inside an otherwise pure static HTML document.
Drift Static provides native, first-class Islands Architecture powered by client:* directives and hydrateIslands() from driftjs-dom.
The Client Directives
DriftJS provides five fine-grained hydration strategies:
Client Load: Eager Hydration
Hydrates the component immediately as soon as the page loads:
<script>
import NavigationBar from '../components/NavigationBar.drift';
</script>
<NavigationBar client:load />
- Best for: Critical above-the-fold interactive components (e.g. mobile navigation drawers, primary search bars).
Client Idle: Idle Hydration
Defers hydration until the browser's main thread is idle using requestIdleCallback() (with fallback to setTimeout):
<script>
import NewsletterSignup from '../components/NewsletterSignup.drift';
</script>
<NewsletterSignup client:idle />
- Best for: Secondary components that don't need immediate responsiveness (e.g. analytics widgets, feedback forms).
Client Visible: Viewport Intersection
Hydrates the component only when it scrolls into view using IntersectionObserver:
<script>
import HeavyChart from '../components/HeavyChart.drift';
</script>
<HeavyChart client:visible data={chartData} />
- Best for: Below-the-fold content, image carousels, and complex data visualizations.
Client Interaction: User Triggered
Delays hydration until the user explicitly interacts with the element (e.g. pointerdown, keydown, or focusin):
<script>
import CommentsSection from '../components/CommentsSection.drift';
</script>
<CommentsSection client:interaction />
- Best for: Complex modals, expandable comment sections, or widgets the user might never open.
Client Media: Media Query Matching
Hydrates only when a specific CSS media query condition evaluates to true:
<script>
import MobileDrawer from '../components/MobileDrawer.drift';
</script>
<MobileDrawer client:media="(max-width: 768px)" />
- Best for: Device-specific interactive components (e.g. mobile bottom navigation sheets that should remain dormant on desktop).
How Islands Are Rendered and Hydrated
1. Build Phase: Scanner and Bundler
scanIslandsfinds all<Component client:* />tags across your project.bundleIslandsuses Vite to generate an optimized island entry bundle (/assets/islands-[hash].js) registering the island components withhydrateIslands().
2. Server HTML Serialization
When DriftServerVM renders an island, it wraps the component's static HTML inside a container with data-drift-* attributes:
<div
data-drift-island="Counter"
data-drift-trigger="visible"
data-drift-props="{"initial":10}"
>
<button>Count: 10</button>
</div>
3. Browser Selective Hydration
When the trigger condition fires (e.g. element scrolls into view):
hydrateIslands()mounts aDriftClientVMinstance.- The VM claims the existing server-rendered HTML nodes using
HydrationCursor. - Event listeners and reactive bindings are activated with zero flicker or DOM reconstruction.