Client Directive Hydration Sequence in Nested Component Trees

Short answer

Parent client:load does not override a child client:visible. The child’s hydration trigger remains viewport-based. The parent must hydrate first so the child’s DOM node exists, after which the child’s Intersection Observer can be attached and will fire independently when the element enters the viewport.

client:only nested inside a client:load wrapper is rendered with no SSR markup and mounts client-side only, after the parent has hydrated. It does not block the parent.

Confirmed facts

• Astro processes islands in a single-pass, depth-first order, applying directives top-down. Parent directives are resolved before children.
• client:load hydrates on initial page load, immediately after the DOM is ready for that island.
• client:visible defers hydration until the element intersects the viewport via Intersection Observer.
• client:only suppresses server rendering for that island entirely; only a client-side placeholder is emitted.

Likely explanation for nesting

With a client:visible child inside a client:load parent:

1. The parent island hydrates on load. Its DOM becomes interactive.
2. Once the parent DOM exists, Astro registers the child island. The child’s client:visible observer is set up, but hydration is not executed yet.
3. The child hydrates only when its element enters the viewport, independent of the parent’s hydrated state. The parent does not postpone the trigger, it merely provides the mount point.

With client:only inside client:load:

1. The parent client:load island hydrates normally with SSR markup.
2. The child client:only island has no SSR output. After the parent hydrates, Astro mounts the child purely on the client. The parent hydration is not blocked.

Assumptions and uncertainty

Hydration directive ordering changed between Astro v1.x and v2.x. Exact timing of observer registration relative to parent hydration may vary by minor release. Intersection Observer behavior can also be affected by browser settings or polyfills.

Practical verification for this case

• Inspect rendered elements for data-astro-component and data-client attributes. client:load islands receive immediate script attachment; client:visible islands show lazy attachment until scroll.
• Open DevTools Performance and look for hydration events. Parent client:load should appear on load; child client:visible should appear on scroll.
• For client:only, confirm the server HTML contains no component markup for the child, only a client placeholder.

To give a version-specific recommendation, please confirm the Astro major version in use. Behavior differs meaningfully between v1 and v2+.