Astro client:load Directive Guide

Learn how Astro’s client:load directive hydrates a component immediately after the page loads, with a concrete React example, limits, and common pitfalls.

Quick answer

Add the client:load directive to any framework component in an Astro file to make that component hydrate as soon as the page’s initial HTML is painted. The rest of the page stays static, giving you interactive behavior without a full‑page JavaScript bundle.

How it works – a worked example

Assume you have an Astro project set up with the React adapter (@astrojs/react).

Install the adapter if you haven’t already:

npm install @astrojs/react react react-dom

Create a simple interactive component, e.g. src/components/Counter.jsx:

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    
      Count: {count}
       setCount(count + 1)}>+1
    
  );
}

Use the component in an Astro page and add client:load:

---
import Counter from '../components/Counter.jsx';
---
Astro + React Counter

When Astro builds the page:

The Counter component is rendered to HTML on the server (so the initial markup includes the button and a count of 0).
A JavaScript bundle containing the React code for Counter is emitted and referenced by a <script> tag in the HTML.
On the browser, after the initial HTML is painted, Astro’s hydration runner executes that bundle, attaching React’s event listeners and making the button functional.

Limits and trade‑offs

Framework compatibility

The directive only works with components built for a framework that has an installed Astro adapter (React, Preact, Svelte, Vue, Solid). If you forget to install @astrojs/react (or the equivalent for your framework), the component will render but no JavaScript will be sent, leaving it non‑interactive.

Payload impact

Every client:load component adds its framework runtime and any imported libraries to the page’s JavaScript bundle. Using the directive on many large components can increase time‑to‑interactive (TTI) and offset the benefits of partial hydration.

Server‑side HTML size

Because the component is still rendered on the server, its static markup contributes to the initial HTML size. Very large components (e.g., a rich‑text editor with extensive static markup) can make the first paint slower even though hydration happens early.

Duplicate hydration

Nesting a client:load inside another client directive (e.g., client:idle) can cause the same component to be hydrated twice, leading to warnings or errors in the console.

Common mistakes and how to avoid them

Missing adapter: After adding client:load, run npm run dev and check the network tab for a script tag matching the component’s name. If it’s absent, verify that the appropriate @astrojs/* adapter is installed and added to astro.config.mjs.
Over‑hydrating static content: A component that only displays props (no state or event listeners) does not need any client directive. Using client:load here wastes bandwidth. Prefer leaving it bare or using client:only if you need the component but want zero hydration.
Relying on browser‑only APIs during SSR: If the component accesses window, document, or navigator during its initial render, the server will throw an error. Guard such code with if (typeof window !== 'undefined') or move it into an effect (useEffect for React) that runs only on the client.
Incorrect nesting: Avoid patterns like <Outer client:idle><Inner client:load /></Outer>. If you need different hydration strategies, place them on sibling components or restructure the layout.

Verification checklist (no output claimed)

Start the dev server: npm run dev. Open the page in a browser and open DevTools → Network. Reload the page and look for a script request whose name includes the component (e.g., Counter.[hash].js).
In the Elements panel, confirm the initial HTML contains the rendered markup (e.g., the button and count).
After the page loads, interact with the component (click the button). If the UI updates, hydration succeeded.
For a production preview, run npm run build && npm run preview and repeat the network/element checks. Ensure no hydration mismatch warnings appear in the console.

Using Astro’s client:load Directive for Immediate Component Hydration