Lazy Hydrating Nuxt Components on Visibility

Keep below-the-fold components server-rendered but defer their JavaScript and hydration until they approach the viewport, using Vue 3.5's defineAsyncComponent({ hydrate: hydrateOnVisible() }) — or Nuxt's <LazyX hydrate-on-visible /> — so the HTML is visible immediately and only the interactivity waits for an IntersectionObserver.

Problem / Scenario Context

A Nuxt product page server-renders a review section with a rich filtering widget, a Q&A accordion and a recommendations carousel, all near the bottom. Hydration of these components on page load takes 250 ms on a mid-range phone, most of it for code the user might never interact with, and it delays the "Add to cart" button's first interaction. Replacing them with client-only lazy components removes the cost but also removes the server-rendered content: reviews disappear from the initial HTML, search engines lose them, and the page jumps when they load.

What the page needs is lazy hydration: server-render the HTML as usual, but defer hydrating it. The Vue Observer Composables topic covers composables; this page applies observers to hydration.

Mechanics Explanation

Hydration attaches Vue's component instances, reactivity and event listeners to server-rendered DOM. Until a component is hydrated, its HTML is visible but inert — clicks on its buttons do nothing.

Vue 3.5 lazy hydration. defineAsyncComponent accepts a hydrate strategy for server-rendered async components. hydrateOnVisible(options) uses an IntersectionObserver (accepting rootMargin/threshold) on the component's root elements: until they intersect, the component's code is not loaded and its DOM is not hydrated; on intersection, Vue loads the chunk and hydrates in place. Other strategies include hydrateOnIdle, hydrateOnInteraction and hydrateOnMediaQuery.

Nuxt (3.16+ / 4) exposes the same strategies declaratively on auto-imported Lazy components: <LazyReviewFilters hydrate-on-visible />, with variants such as hydrate-on-idle, hydrate-on-interaction and hydrate-never.

Because the HTML is server-rendered, nothing shifts when hydration happens. The risk is the opposite: a user who scrolls to the section and clicks before hydration completes gets no response. hydrateOnInteraction replays the triggering event after hydration; hydrateOnVisible with a generous rootMargin usually hydrates before the user arrives.

Comparison Table: Loading Strategies for Below-the-Fold Components

Minimal Reproducible Example

<!-- pages/product/[id].vue -->
<template>
  <ProductHero :product="product" />
  <AddToCart :product="product" />
  <ReviewFilters :reviews="reviews" />      <!-- hydrates on load: 120 ms -->
  <QAAccordion :items="qa" />               <!-- hydrates on load: 60 ms -->
  <Recommendations :ids="recs" />           <!-- hydrates on load: 70 ms -->
</template>

The Performance panel shows a long hydration task right after load, and interaction with Add to cart is delayed while it runs.

Production-Safe Solution

<!-- Nuxt: declarative lazy hydration on auto-imported Lazy components -->
<template>
  <ProductHero :product="product" />
  <AddToCart :product="product" />
  <LazyReviewFilters hydrate-on-visible :reviews="reviews" />
  <LazyQAAccordion hydrate-on-interaction :items="qa" />
  <LazyRecommendations hydrate-on-visible :ids="recs" />
</template>

// Plain Vue 3.5 SSR: the same with defineAsyncComponent.
import { defineAsyncComponent, hydrateOnVisible } from 'vue';

export const ReviewFilters = defineAsyncComponent({
  loader: () => import('./ReviewFilters.vue'),
  hydrate: hydrateOnVisible({ rootMargin: '300px' }),     // start before it is on screen
});

The review filters hydrate when they come within 300 px of the viewport; the Q&A accordion waits for the first click or focus and replays it after hydrating, so the first toggle still works; recommendations hydrate on visibility. None of them ship JavaScript on initial load, all of them are in the server HTML.

For versions without built-in strategies, a manual fallback wraps server-rendered content and mounts the interactive component when visible — accepting that, without true lazy hydration, the wrapper's content is re-rendered by the client component rather than hydrated:

<!-- LazyOnVisible.vue: fallback for older setups -->
<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue';
const root = ref<HTMLElement>(); const show = ref(false); let io: IntersectionObserver | undefined;
onMounted(() => {
  io = new IntersectionObserver(([e]) => { if (e.isIntersecting) { show.value = true; io?.disconnect(); } },
    { rootMargin: '300px' });
  io.observe(root.value!);
});
onBeforeUnmount(() => io?.disconnect());
</script>
<template>
  <div ref="root"><slot v-if="show" /><slot v-else name="placeholder" /></div>
</template>

Pitfalls

Hydration mismatches surface later. A component whose server and client renders differ used to warn on page load; with lazy hydration it warns — and may re-render — when it scrolls into view, where a visual correction is more noticeable. Keep observer-driven state out of server rendering; see hydration mismatch from observer-driven class toggles.

Props and data are still serialised. The component's props travel in the page payload even if it never hydrates. Lazy hydration saves JavaScript and hydration work, not payload size.

Anchors and deep links. A user arriving at #reviews lands on the component immediately; hydrateOnVisible fires right away, which is correct. With hydrate-on-interaction, the first click is replayed, so it also works.

Nested lazy components each wait for their own trigger. A lazily hydrated parent must hydrate before its children can, so keep lazy boundaries at one level where possible.

Verification Steps

• View source: lazily hydrated components' HTML must be present.
• Network panel: their chunks load only when scrolled near (or interacted with).
• Performance panel: the load-time hydration task shrinks; interaction with above-the-fold controls is faster.
• Scroll quickly and click a lazily hydrated control; it must respond (with enough margin or event replay).
• Check the console for hydration mismatch warnings when components hydrate.

Common Mistakes to Avoid

• Client-only rendering for SEO-relevant content. It removes the HTML; use lazy hydration instead.
• Lazy-hydrating above-the-fold controls. They become unresponsive at the worst moment.
• A zero margin for visible hydration. Users reach the component before it is interactive.
• Rendering observer state on the server. Mismatches appear when the component hydrates.

FAQ

Related

• Deferring Observer Setup Until After Hydration — the observers inside hydrated components
• Lazy Loading Components with Dynamic Import — client-side lazy loading
• Observers in React Server Components and Client Boundaries — the React equivalent

↑ Back to Vue Observer Composables