Lazy Loading | Bootspring Docs

Patterns for lazy loading components, data, and assets on demand.

Overview#

Lazy loading improves initial page load by deferring non-critical resources. This pattern covers:

Dynamic imports with next/dynamic
React.lazy with Suspense
Intersection Observer
Virtual lists
Image lazy loading

Prerequisites#

npm install @tanstack/react-virtual

Code Example#

Dynamic Imports#

// app/page.tsx
import dynamic from 'next/dynamic'

// Basic dynamic import
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <div className="h-64 animate-pulse bg-gray-200" />
})

// With SSR disabled (client-only component)
const MapComponent = dynamic(
  () => import('@/components/Map'),
  { ssr: false }
)

// Named exports
const Modal = dynamic(
  () => import('@/components/Modals').then(mod => mod.Modal)
)

export default function Page() {
  return (
    <div>
      <HeavyChart data={chartData} />
      <MapComponent location={location} />
    </div>
  )
}

React.lazy with Suspense#

// components/Dashboard.tsx
import { Suspense, lazy } from 'react'

const Analytics = lazy(() => import('./Analytics'))
const Reports = lazy(() => import('./Reports'))
const Settings = lazy(() => import('./Settings'))

export function Dashboard({ tab }: { tab: string }) {
  return (
    <div>
      <Suspense fallback={<TabSkeleton />}>
        {tab === 'analytics' && <Analytics />}
        {tab === 'reports' && <Reports />}
        {tab === 'settings' && <Settings />}
      </Suspense>
    </div>
  )
}

function TabSkeleton() {
  return (
    <div className="space-y-4 p-4">
      <div className="h-8 w-1/3 animate-pulse rounded bg-gray-200" />
      <div className="h-64 animate-pulse rounded bg-gray-200" />
    </div>
  )
}

Intersection Observer#

// components/LazySection.tsx
'use client'

import { useRef, useEffect, useState, ReactNode } from 'react'

interface Props {
  children: ReactNode
  fallback?: ReactNode
  rootMargin?: string
}

export function LazySection({
  children,
  fallback = <div className="h-64" />,
  rootMargin = '100px'
}: Props) {
  const ref = useRef<HTMLDivElement>(null)
  const [isVisible, setIsVisible] = useState(false)

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true)
          observer.disconnect()
        }
      },
      { rootMargin }
    )

    if (ref.current) {
      observer.observe(ref.current)
    }

    return () => observer.disconnect()
  }, [rootMargin])

  return (
    <div ref={ref}>
      {isVisible ? children : fallback}
    </div>
  )
}

// Usage
<LazySection>
  <HeavyComponent />
</LazySection>

Lazy Image Loading#

// components/LazyImage.tsx
'use client'

import Image from 'next/image'
import { useState } from 'react'

interface Props {
  src: string
  alt: string
  width: number
  height: number
  className?: string
}

export function LazyImage({ src, alt, width, height, className }: Props) {
  const [isLoaded, setIsLoaded] = useState(false)

  return (
    <div className={`relative ${className}`}>
      {/* Blur placeholder */}
      {!isLoaded && (
        <div
          className="absolute inset-0 animate-pulse bg-gray-200"
          style={{ aspectRatio: `${width}/${height}` }}
        />
      )}

      <Image
        src={src}
        alt={alt}
        width={width}
        height={height}
        loading="lazy"
        onLoad={() => setIsLoaded(true)}
        className={`transition-opacity duration-300 ${
          isLoaded ? 'opacity-100' : 'opacity-0'
        }`}
      />
    </div>
  )
}

// With blur placeholder from Next.js
export function BlurImage({
  src,
  alt,
  blurDataUrl,
  ...props
}: Props & { blurDataUrl: string }) {
  return (
    <Image
      src={src}
      alt={alt}
      {...props}
      loading="lazy"
      placeholder="blur"
      blurDataURL={blurDataUrl}
    />
  )
}

Virtual List#

// components/VirtualList.tsx
'use client'

import { useVirtualizer } from '@tanstack/react-virtual'
import { useRef } from 'react'

interface Props<T> {
  items: T[]
  itemHeight: number
  renderItem: (item: T, index: number) => React.ReactNode
}

export function VirtualList<T>({ items, itemHeight, renderItem }: Props<T>) {
  const parentRef = useRef<HTMLDivElement>(null)

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => itemHeight,
    overscan: 5
  })

  return (
    <div
      ref={parentRef}
      className="h-[500px] overflow-auto"
    >
      <div
        style={{
          height: `${virtualizer.getTotalSize()}px`,
          position: 'relative'
        }}
      >
        {virtualizer.getVirtualItems().map(virtualItem => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualItem.size}px`,
              transform: `translateY(${virtualItem.start}px)`
            }}
          >
            {renderItem(items[virtualItem.index], virtualItem.index)}
          </div>
        ))}
      </div>
    </div>
  )
}

// Usage
<VirtualList
  items={largeDataset}
  itemHeight={60}
  renderItem={(item) => <ListItem item={item} />}
/>

Conditional Feature Loading#

// components/FeatureLoader.tsx
'use client'

import dynamic from 'next/dynamic'

const features = {
  analytics: dynamic(() => import('@/features/Analytics')),
  collaboration: dynamic(() => import('@/features/Collaboration')),
  aiAssistant: dynamic(() => import('@/features/AIAssistant'))
}

interface Props {
  enabledFeatures: (keyof typeof features)[]
}

export function FeatureLoader({ enabledFeatures }: Props) {
  return (
    <>
      {enabledFeatures.map(feature => {
        const Component = features[feature]
        return <Component key={feature} />
      })}
    </>
  )
}

Preloading on Intent#

// components/Navigation.tsx
import Link from 'next/link'
import dynamic from 'next/dynamic'

// Preload the heavy modal component
const HeavyModal = dynamic(() => import('@/components/HeavyModal'))

export function Navigation() {
  // Preload when user shows intent
  function handleMouseEnter() {
    import('@/components/HeavyModal')
  }

  return (
    <nav>
      {/* Prefetch on hover/focus (default behavior) */}
      <Link href="/dashboard" prefetch={true}>
        Dashboard
      </Link>

      {/* Disable prefetch for rarely visited */}
      <Link href="/settings" prefetch={false}>
        Settings
      </Link>

      {/* Preload component on hover */}
      <button onMouseEnter={handleMouseEnter}>
        Open Modal
      </button>
    </nav>
  )
}

Route-Based Code Splitting#

// Next.js App Router automatically code-splits by route
// app/
// |-- page.tsx           -> main chunk
// |-- dashboard/
// |   |-- page.tsx       -> dashboard chunk
// |-- settings/
// |   |-- page.tsx       -> settings chunk
// |-- admin/
//     |-- page.tsx       -> admin chunk

// Parallel route loading
// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  activity
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  activity: React.ReactNode
}) {
  return (
    <div className="grid grid-cols-3 gap-4">
      <div className="col-span-2">{children}</div>
      <div className="space-y-4">
        {analytics}
        {activity}
      </div>
    </div>
  )
}

// app/dashboard/@analytics/page.tsx
// app/dashboard/@activity/page.tsx
// These load in parallel, each as separate chunks

Usage Instructions#

Use next/dynamic for components that aren't needed immediately
Set ssr: false for client-only components (maps, charts)
Use Intersection Observer for below-the-fold content
Implement virtual lists for large datasets
Preload on user intent for better perceived performance

Best Practices#

Analyze first - Use bundle analyzer to find heavy components
Critical path - Don't lazy load above-the-fold content
Loading states - Always provide meaningful fallbacks
Prefetch strategically - Balance bandwidth vs speed
Virtual lists - Use for lists with >100 items
Image optimization - Use Next.js Image with lazy loading
Monitor impact - Track Core Web Vitals improvements

Bundle Analysis - Identify heavy imports
Caching - Cache loaded resources
Optimization - General optimizations
Code Splitting - Split bundles