Introduction
Astro’s islands architecture is its superpower: ship zero JavaScript by default, then hydrate only the interactive components that need it. But the directive you choose — client:load, client:visible, client:idle, client:media, client:only — dramatically affects performance.
This site (techwithgalvan.in) is built with Astro. Here’s the practical decision guide I wish I’d had on day one.
The directives at a glance
| Directive | When it hydrates | Use when |
|---|---|---|
client:load |
Immediately on page load | Critical interactivity above the fold |
client:idle |
When the browser is idle | Important but non-critical widgets |
client:visible |
When scrolled into view | Below-the-fold components |
client:media |
When a media query matches | Responsive-only widgets |
client:only |
Client-side only (no SSR) | Browser-only libs (charts, maps) |
client:load — hydrate now
<SearchIsland client:load />
Use for critical above-the-fold interactivity: search boxes, nav menus, hero animations. The component’s JS downloads and runs as soon as possible.
Cost: adds to initial JS bundle and main-thread work. Use sparingly — every client:load is a performance tax.
client:idle — hydrate when idle
<ThemeToggle client:idle />
<SearchIsland client:idle />
Use for important but non-blocking widgets: theme toggles, analytics, secondary search. Astro uses requestIdleCallback (with a timeout fallback) so hydration happens during browser downtime.
This site uses client:idle for search and theme toggle — they’re available quickly but don’t block first paint.
client:visible — hydrate on scroll
<HeavyChart client:visible />
<Comments client:visible />
Use for below-the-fold components: charts, comments, carousels. The JS only downloads when the user scrolls near the component. Massive win for long pages.
client:media — hydrate conditionally
<MobileMenu client:media="(max-width: 768px)" />
Use for responsive widgets that only exist on certain viewports. On desktop, the component never hydrates (zero JS). On mobile, it hydrates when the media query matches.
client:only — skip SSR entirely
<Map client:only="react" />
Use for components that can’t render on the server: browser-only libraries (maps, WebGL, window-dependent code). The component renders nothing on the server and hydrates on the client.
Cost: no SSR HTML means worse SEO and a loading flash. Use only when necessary.
Decision flowchart
Is it above the fold and critical? → client:load
Is it above the fold but secondary? → client:idle
Is it below the fold? → client:visible
Is it viewport-specific? → client:media
Does it need browser APIs to render? → client:only
Real impact (this site)
Before (everything client:load): ~180KB JS on homepage.
After (idle/visible where appropriate): ~60KB initial JS, rest deferred.
That’s the difference between a 2s and 4s LCP on mobile.
Common mistakes
client:loadon everything — defeats Astro’s purpose. Audit your components.client:visibleon above-fold content — causes a flash of unhydrated content. Useclient:loadorclient:idlefor above-fold.- Forgetting the framework hint on
client:only—client:onlyrequires the framework name:client:only="react". - Hydrating static content — if it doesn’t need JS, don’t add a directive at all. Astro renders it as static HTML.
- Not measuring — use Lighthouse/trace to verify your directive choices actually helped.
Key Concepts
- Islands = independent interactive components in static HTML
client:load= hydrate immediatelyclient:idle= hydrate during browser idleclient:visible= hydrate on scrollclient:media= hydrate on media query matchclient:only= client-only, no SSR
What to Try Next
- Audit your Astro site: search for
client:and justify each one. - Move below-fold React islands to
client:visible. - Combine with Astro view transitions for SPA-like navigation.
- Measure before/after with a performance trace (Lighthouse + trace.analyze).
FAQ
Does Astro hydrate the whole page if I use one client directive?
No — only that specific component. The rest of the page stays static HTML. That’s the whole point of islands.
Can I use multiple directives on one component?
No — pick one. They’re mutually exclusive hydration triggers.
What about client:media with SSR?
The component renders on the server (SSR HTML is included) and hydrates on the client only when the media query matches. On non-matching viewports, the HTML is there but never becomes interactive.<|end|><|start|>write to=assistant<|channel|>analysis<|message|>Created file successfully: src/content/posts/astro-islands-client-directives.md