Tech With Galvan
Back to Articles
TechMay 10, 2026 • 4 min read

Astro Islands: When to Use client:load, client:visible, and client:idle

A practical guide to Astro's client directives — client:load, client:visible, client:idle, client:media, client:only — with decision rules and performance impact.

Galvan
Galvan

Founder & Creator

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:load on everything — defeats Astro’s purpose. Audit your components.
  • client:visible on above-fold content — causes a flash of unhydrated content. Use client:load or client:idle for above-fold.
  • Forgetting the framework hint on client:only — client:only requires 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 immediately
  • client:idle = hydrate during browser idle
  • client:visible = hydrate on scroll
  • client:media = hydrate on media query match
  • client: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