Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Components and Islands

Client Directives: load, idle, visible, media, only

Control when Astro islands hydrate with client:load, client:idle, client:visible, client:media and client:only, and learn how to choose the right one.

An island is interactive only after its JavaScript has loaded and run. Client directives decide when that happens. Choosing well is one of the biggest performance levers you have in Astro: a component that hydrates when the visitor actually needs it costs far less than one that fights for bandwidth at page load.

You apply a directive as an attribute on a framework component:

ASTRO
---
import Search from "../components/Search.jsx";
---
<Search client:load />

The five directives

client:load

Load and hydrate the component immediately when the page loads. Use it for UI that must be interactive at once: a primary navigation menu, an above-the-fold form, a cookie banner.

ASTRO
<Menu client:load />

client:idle

Wait until the browser has finished the initial load and fires requestIdleCallback, then hydrate. Good for components that are not needed in the first second: a chat button, a newsletter signup. You can set a timeout in milliseconds so older browsers do not wait forever:

ASTRO
<ChatWidget client:idle />
<ChatWidget client:idle={{ timeout: 500 }} />

client:visible

Hydrate when the component scrolls into view, using an IntersectionObserver. The JavaScript is not even downloaded until then. This is ideal for anything below the fold: comments, image carousels, maps, charts.

ASTRO
<Comments client:visible />
<Map client:visible={{ rootMargin: "200px" }} />

The rootMargin option starts loading a little before the component is on screen so the user sees no delay.

client:media

Hydrate only if a CSS media query matches. It suits components that exist only on certain screen sizes, such as a mobile drawer menu:

ASTRO
<MobileMenu client:media="(max-width: 50em)" />

On a desktop screen the query never matches, so the code is never downloaded.

client:only

Skip server rendering entirely. The component is rendered in the browser only. You must tell Astro which framework to use because it cannot detect it from the server render:

ASTRO
<MapWidget client:only="react" />

Use it when the component cannot run on the server at all, for example because it touches window during import. Because there is no server HTML, give the visitor something to look at with a fallback slot:

ASTRO
<MapWidget client:only="react">
  <p slot="fallback">Loading map...</p>
</MapWidget>

When does it hydrate?

load Right away
idle When the browser is free
visible When scrolled into view
media When a query matches
1 / 2

Choosing a directive

Ask these questions in order:

  1. Does the component need to be interactive immediately, above the fold? Use client:load.
  2. Is it visible but not urgent? Use client:idle.
  3. Is it below the fold or inside a tab? Use client:visible.
  4. Does it exist only on some screens? Use client:media.
  5. Does it break when rendered on the server? Use client:only.

If you are unsure, start with client:visible or client:idle, measure, and move to client:load only when the delay is noticeable. The cheapest hydration is the hydration that never happens.

Rules and gotchas

  • Directives work on framework components (React, Vue, Svelte and others), not on .astro components. An .astro component never hydrates; it is HTML. Use a <script> for its behaviour.
  • A directive applies to the component and everything inside it. If an island wraps static children, the children are passed through as HTML.
  • The first island that uses a framework brings that framework's runtime along. Further islands of the same framework reuse it.
  • You can add your own directive through an integration, such as client:click, if the built-ins are not enough.
  • Hydration mismatches can occur if the server render and the first client render differ, for example because of Math.random() or Date.now() in the output.

Stand-in: a hydration scheduler

The following stand-in implements the decisions behind the directives. It takes a page of islands and a "browser state" and reports which ones hydrate at each moment.

Node.js Stand-in: when does each island hydrate?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: visible with a margin

client:visible uses an observer with a rootMargin so that loading starts early. This stand-in works out which elements to start loading as the user scrolls, using plain numbers instead of a DOM.

Node.js Stand-in: visibility with rootMargin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Measuring the difference

Open the browser dev tools network panel and compare the same page with client:load on every island and with thoughtful directives. Look at the number of JavaScript requests and their size before the page becomes interactive. The Lighthouse score for total blocking time often improves noticeably with client:visible alone.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which directive downloads no JavaScript until the component scrolls into view?

    client:visible waits for an IntersectionObserver to report the component as visible.
  2. 2. What is required with client:only?

    There is no server render to detect the framework from, so you name it.
  3. 3. Can you add client:load to an .astro component to make it interactive?

    Astro components never hydrate. Use a script tag or a framework component for behaviour.
  4. 4. Which directive suits a menu that only exists below 50em width?

    client:media hydrates only when the given media query matches.

Summary

  • client:load hydrates at once; client:idle waits for browser idle time; client:visible waits for scrolling into view.
  • client:media hydrates when a media query matches; client:only skips server rendering and needs the framework name.
  • Directives apply to framework components, not .astro components.
  • Prefer the laziest directive that still feels instant, and measure the result.
  • Avoid hydration mismatches by keeping the first server and client renders identical.

Next: Sharing State Between Islands