next-lazy-hydration-on-scroll

⚠️ Pages Directory Only - For Next.js App Directory better use built-in streaming.

Optimize Next.js app performance by lazy loading and hydrating components when they enter the viewport.

• ⚡️ Lower Total Blocking Time (TBT)
• 📦 Smaller Bundle Size
• 🚀 Improved Performance

Installation

npm install next-lazy-hydration-on-scroll
# or
yarn add next-lazy-hydration-on-scroll
# or
pnpm add next-lazy-hydration-on-scroll

Usage

import { lazyHydrate } from 'next-lazy-hydration-on-scroll'

const LazyComponent = lazyHydrate(() => import('./components/HeavyComponent'), {
  LoadingComponent: () => <div>Loading...</div>, // Optional
  wrapperElement: 'div', // Optional, defaults to 'section'
})

export default function Page() {
  return (
    <div>
      <header>Always hydrated</header>
      <LazyComponent wrapperProps={{ className: 'my-wrapper', id: 'lazy-component' }} /> {/* Hydrates when scrolled into view */}
    </div>
  )
}

Options

| Option | Type | Default | Description | | ------------------ | ----------------------------- | ------------- | ------------------------------------------------------- | | rootMargin | string | '0px 250px' | Margin around the root element for IntersectionObserver | | LoadingComponent | ComponentType | undefined | Component to show while loading | | wrapperElement | keyof JSX.IntrinsicElements | 'section' | HTML element to wrap the component |

Component Props

| Prop | Type | Description | | -------------- | --------------------- | ------------------------------------ | | wrapperProps | Record<string, any> | Props to pass to the wrapper element |

How It Works

1. Server renders full HTML content
2. Components remain static until scrolled into view
3. When component enters viewport:
   • JavaScript is loaded
   • Component is hydrated
   • Interactivity is enabled

Implementation Requirements

• Keep components in separate files
• Avoid barrel files (index.ts that re-exports components)
• Import components directly:

// ✅ Correct
import { ComponentA } from './components/ComponentA'

// ❌ Avoid
// components/index.ts with re-exports

Browser Support

Works in all modern browsers supporting IntersectionObserver (IE11+ with polyfill).

Notes

• SEO friendly - content is pre-rendered
• Components are wrapped in customizable elements (default: <section>) for stable viewport detection
• Works with Next.js 12 and above

FAQ

Q: Does it affect SEO?

A: No - all content is pre-rendered and visible to search engines.

Q: What's the browser support?

A: All modern browsers (IE11+ with polyfill).

Q: Why are components wrapped in an element?

A: For two reasons: to provide a stable element for IntersectionObserver tracking, and to handle hydration mismatches with suppressHydrationWarning.

Q: Can I customize the wrapper element?

A: Yes - use the wrapperElement option to specify any valid HTML element (e.g., 'div', 'article') and pass props to it using the wrapperProps prop.

Q: Why is dangerouslySetInnerHTML used?

A: It prevents React from hydrating down the component tree, allowing to preserve server-rendered content while controlling when hydration occurs.

View Demo | GitHub Repository