Astro Client Directives — Hydration Control

In this tutorial, you will learn about Astro Client Directives. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Astro client directives: client:load, client:idle, client:visible, client:media, client:only and how to control when interactive islands hydrate.

In this lesson, you'll explore each client directive in detail, understand when to use each one, and learn how to choose the right hydration Strategy for your components to maximize performance.

What You'll Learn

The behavior of each client directive, how to combine them with media queries, and how to choose the optimal hydration strategy for different component types.

Why It Matters

Choosing the wrong directive wastes bandwidth or delays interactivity. Matching the directive to the component's visibility and importance improves both perceived and actual performance.

Real-World Use

DodaTech's tutorial site uses client:visible for code copy buttons (they don't need to load until the user scrolls to code) and client:load for the site-wide search.

flowchart TD
    A[Interactive Component] --> B{Where is it?}
    B -->|Above fold| C[client:load]
    B -->|Below fold| D[client:visible]
    B -->|Non-critical| E[client:idle]
    B -->|Responsive| F[client:media]
    B -->|No SSR| G[client:only]
    style A fill:#ff5a03,color:#fff

Directive Reference

client:load

Loads and hydrates the component immediately when the page loads:

<SiteHeader client:load />

Use for: navigation menus, search bars, any component visible above the fold that needs immediate interactivity.

client:idle

Loads after the browser is idle (uses requestIdleCallback):

<AnalyticsTracker client:idle />
<ChatWidget client:idle />

Use for: non-critical components that can wait a few seconds after page load.

client:visible

Loads when the element scrolls into the viewport:

<CommentSection client:visible />
<RelatedPosts client:visible />

Use for: components below the fold. Users won't miss them since they load exactly when needed.

client:media

Loads only when a CSS media query matches:

<DesktopChart client:media="(min-width: 1024px)" />
<MobileNav client:media="(max-width: 767px)" />

Use for: responsive components that only work on certain screen sizes.

client:only

Renders only on the client with no SSR:

<ClientMap client:only="react" />
<RealTimeClock client:only="vue" />

Use for: components that depend on browser APIs (localStorage, geolocation) or that can't be server-rendered.

Combining Directives

You can combine client:media with other directives through nested elements, but the cleanest approach is to use conditional rendering in the parent:

---
const isDesktop = true; // Determine at build or request time
---
{isDesktop && <DesktopChart client:visible />}
{!isDesktop && <MobileChart client:visible />}

Performance Comparison

Common Mistakes

1. Using client:load for everything: This re-hydrates all components immediately, negating island performance benefits.
2. Forgetting the directive entirely: Framework components without a directive render as static HTML that doesn't respond to user interaction.
3. Using client:visible for above-fold content: Components visible on load should use client:load for instant interactivity.
4. Specifying the wrong framework in client:only: The framework name must match the integration. client:only="react" requires @astrojs/react.
5. Putting client:only components in SSR paths: These components don't render during SSR, so their loading state must handle empty server output gracefully.

Practice Questions

1. Which directive should you use for a navigation menu? Answer: client:load. Navigation is visible above the fold and needs immediate interactivity.

2. How does client:idle determine when to load? Answer: It uses requestIdleCallback to schedule hydration when the browser has free time.

3. Can you use multiple directives on one component? Answer: No. Each component gets a single client:* directive. Use conditional rendering in the parent for complex logic.

4. What happens to a client:only component during SSR? Answer: It renders nothing during SSR. A placeholder or loading state should handle the empty output.

Challenge

Build a dashboard page with four components: a search bar (client:load), a real-time clock (client:only), a chart that loads on desktop only (client:media), and a recommendations section (client:visible).

Mini Project

Create a product page with an image gallery using client:visible for thumbnails below the fold, a color picker with client:load above the fold, and a reviews section with client:idle.

FAQ

What's Next

Learn how to use Astro MDX to combine Markdown with interactive components in content pages.