Client Directives: Transitioning from client:load to client:visible for hydration optimization

Astro 4.x does not provide a native automatic space-reservation mechanism for islands using client:visible. The directive only changes when hydration is triggered via Intersection Observer; it does not inject a placeholder or reserve layout size.

Confirmed facts

• client:visible defers hydration until the island element intersects the viewport. Initial JavaScript execution is reduced compared with client:load.
• The server-rendered markup for the island is sent and visible before hydration runs. Astro does not add a wrapper that reserves height for the hydrated state.
• There is no built-in Astro option to auto-reserve space for client:visible islands in Astro 4.x.

Likely explanation for CLS risk

Layout shift risk comes from a size mismatch between the static server HTML and the fully hydrated interactive component. With dynamic heights determined after hydration, the browser can reflow when the island mounts and the DOM changes. The Intersection Observer delay makes the shift more noticeable because the component is often below the fold.

Recommended strategy for this case

Reserve space in the static server markup with CSS so the layout is stable before the Intersection Observer triggers hydration.

1. Wrap the island in a container with a stable size. Use min-height or aspect-ratio derived from design for the expected hydrated height.
2. Render a lightweight static skeleton in the Astro markup that matches the visual footprint of the hydrated UI. Keep the skeleton in the same DOM structure to avoid a second shift after hydration.
3. Avoid height-changing DOM mutations on first mount. Initialize state from server props and prevent the component from inserting content that changes its outer height after hydration.

Example pattern:

<div class="island-frame">
  <MyIsland client:visible />
</div>
<style>
.island-frame { min-height: 320px; }
/* or aspect-ratio: 16 / 9 for media */
</style>

Verification

• Inspect rendered HTML and confirm no Astro-injected placeholder reserves size.
• Measure CLS in lab before and after adding the reservation.
• Confirm hydration timing in DevTools to ensure Intersection Observer triggers on viewport entry.
• Compare server-rendered height vs post-hydration height to size the reservation.

One diagnostic that changes the recommendation: is the final hydrated height deterministic from the server markup, or does it depend on client-only data such as a fetch result? If it is client-only and unknown, a fixed min-height with a skeleton is the safest fallback; otherwise the exact height can be reserved.