Nested component hydration order with mixed client directives

Question

Hydration sequencing for parent and child islands
Astro's Islands Architecture allows each component to declare its own hydration strategy via client:load, client:visible, client:idle, or client:only. When a parent island uses one directive and a nested child island uses a different directive, the framework must decide which component hydrates first and whether the parent's hydration waits for the child.
The documentation states that each island hydrates independently, but it does not specify the exact ordering guarantees when directives differ. For example, a client:visible parent containing a client:load child could theoretically hydrate the child before the parent becomes visible, or the parent's Intersection Observer callback might delay the child's hydration until the parent enters the viewport.
This ambiguity affects performance budgets and layout stability, especially when the child component contributes to Largest Contentful Paint or when the parent's server-rendered placeholder differs in size from the hydrated output.

Does Astro guarantee a specific hydration order (parent-first, child-first, or parallel) when directives differ?
Can a client:visible parent block a client:load child from hydrating until the parent intersects the viewport?
Are there documented Intersection Observer threshold or rootMargin defaults that influence this behavior?

Tasadduq Burney · Answer

Answer
Astro does not guarantee a fixed hydration order for nested islands when their client directives differ.
Confirmed facts

Each island is an independent hydration unit; the parent’s directive does not block or wait for the child.
A child marked client:load hydrates as soon as the page’s load event fires, regardless of the parent’s visibility.
A parent marked client:visible delays its own hydration until its IntersectionObserver reports that any part of the island enters the viewport.
The IntersectionObserver used by client:visible uses the browser defaults: threshold: 0 and rootMargin: 0px; Astro does not expose or modify these values.

Likely explanation
Because the two islands resolve their hydration triggers independently, the actual order depends on when each trigger fires. If the load event occurs before the parent scrolls into view, the child logs first; if the parent becomes visible before load (e.g., already in viewport and load fires later), the parent may hydrate first. Network speed, layout shifts, and initial viewport state can shift the order.
Steps to verify in your project

Add a parent island with client:visible that logs “parent hydrated”.
Add a child island inside it with client:load that logs “child hydrated”.
Open the page, open DevTools console, and reload.
Observe which log appears first; then scroll the parent into view (if not already) and note any change.
Optionally cover the parent with off‑screen CSS to keep it invisible; the child should still log on load while the parent log appears only when the parent becomes visible.

If you need to enforce a specific order (e.g., child must wait for parent), consider moving the child’s logic into a shared state or using client:idle on the parent and client:load on the child with a manual trigger, or wrap the child in a client:visible island as well.

Nested component hydration order with mixed client directives

Hydration sequencing for parent and child islands

1 answer

Answer

Confirmed facts

Likely explanation

Steps to verify in your project

Your perspective belongs here.

0 question comments