Selective Hydration

Selective hydration is a performance technique where a page loads as fast, static HTML, and then only the parts that actually need interactivity (a search bar, a dropdown, an interactive demo) get their JavaScript attached after the fact. Instead of loading JavaScript for the entire page, the browser only processes the small interactive pieces. Astro calls this the “Islands Architecture,” where each interactive component gets its JavaScript on its own schedule (immediately, when visible, on first click) while everything else stays as plain HTML.

The Simple Version

Most websites either send all their JavaScript to every visitor (slow) or send none at all (fast but not interactive). Selective hydration is the middle ground. The page loads as static HTML (fast), and then only the parts that actually need interactivity (a dropdown menu, a search bar, an interactive demo) get their JavaScript loaded.

The term “hydration” comes from the idea of “adding water to something dry.” The static HTML is the dry version. Adding JavaScript to make it interactive is the hydration.

Why It Matters

Selective hydration gives you the best of both worlds: the speed of static HTML and the interactivity of JavaScript frameworks like React. Pages load fast because most of the content is just HTML. Then the small interactive pieces “wake up” with their JavaScript, and the user experience feels smooth.

How It’s Used on This Site

Astro calls this the “Islands Architecture.” Most of this site is static HTML (the header, text sections, footer). The interactive “islands” that get hydrated with JavaScript are:

• GlossarySearch on the Dictionary page: search and filter terms instantly
• ExperienceTimeline on the homepage: click roles to open detail modals
• MobileNav: the hamburger menu on smaller screens
• FileClarityDemo at /projects/file-clarity: the interactive before-and-after file explorer

The directive client:load in the code tells Astro which components need JavaScript. Everything else ships as plain, fast HTML.