---

name: lazy-loading-patterns description: Code splitting and lazy loading with React.lazy, Suspense, route-based splitting, intersection observer, and preload strategies for optimal bundle performance. Use when implementing lazy loading or preloading. tags: [lazy-loading, code-splitting, suspense, dynamic-import, intersection-observer, preload, react-19, performance] context: fork agent: frontend-ui-developer version: 1.0.0 author: OrchestKit user-invocable: false

Lazy Loading Patterns

Code splitting and lazy loading patterns for React 19 applications using React.lazy, Suspense, route-based splitting, and intersection observer strategies.

Overview

• Reducing initial bundle size for faster page loads
• Route-based code splitting in SPAs
• Lazy loading heavy components (charts, editors, modals)
• Below-the-fold content loading
• Conditional feature loading based on user permissions
• Progressive image and media loading

Core Patterns

1. React.lazy + Suspense (Standard Pattern)

Copyimport { lazy, Suspense } from 'react';

// Lazy load component - code split at this boundary
const HeavyEditor = lazy(() => import('./HeavyEditor'));

function EditorPage() {
  return (
    <Suspense fallback={<EditorSkeleton />}>
      <HeavyEditor />
    </Suspense>
  );
}

// With named exports (requires intermediate module)
const Chart = lazy(() =>
  import('./charts').then(module => ({ default: module.LineChart }))
);

2. React 19 use() Hook (Modern Pattern)

Copyimport { use, Suspense } from 'react';

// Create promise outside component
const dataPromise = fetchData();

function DataDisplay() {
  // Suspense-aware promise unwrapping
  const data = use(dataPromise);
  return <div>{data.title}</div>;
}

// Usage with Suspense
<Suspense fallback={<Skeleton />}>
  <DataDisplay />
</Suspense>

3. Route-Based Code Splitting (React Router 7.x)

Copyimport { lazy } from 'react';
import { createBrowserRouter, RouterProvider } from 'react-router';

// Lazy load route components
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));
const Analytics = lazy(() => import('./pages/Analytics'));

const router = createBrowserRouter([
  {
    path: '/',
    element: <Layout />,
    children: [
      { path: 'dashboard', element: <Dashboard /> },
      { path: 'settings', element: <Settings /> },
      { path: 'analytics', element: <Analytics /> },
    ],
  },
]);

// Root with Suspense boundary
function App() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <RouterProvider router={router} />
    </Suspense>
  );
}

4. Intersection Observer Lazy Loading

Copyimport { useRef, useState, useEffect, lazy, Suspense } from 'react';

const HeavyComponent = lazy(() => import('./HeavyComponent'));

function LazyOnScroll({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const [isVisible, setIsVisible] = useState(false);

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
          observer.disconnect();
        }
      },
      { rootMargin: '100px' } // Load 100px before visible
    );

    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);

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

// Usage
<LazyOnScroll>
  <Suspense fallback={<ChartSkeleton />}>
    <HeavyComponent />
  </Suspense>
</LazyOnScroll>

5. Prefetching on Hover/Focus

Copyimport { useQueryClient } from '@tanstack/react-query';
import { Link } from 'react-router';

function NavLink({ to, children }: { to: string; children: React.ReactNode }) {
  const queryClient = useQueryClient();

  const prefetchRoute = () => {
    // Prefetch data for the route
    queryClient.prefetchQuery({
      queryKey: ['page', to],
      queryFn: () => fetchPageData(to),
    });

    // Prefetch the component chunk
    import(`./pages/${to}`);
  };

  return (
    <Link
      to={to}
      onMouseEnter={prefetchRoute}
      onFocus={prefetchRoute}
      preload="intent" // React Router preloading
    >
      {children}
    </Link>
  );
}

6. Module Preload Hints

Copy<!-- In index.html or via helmet -->
<link rel="modulepreload" href="/assets/dashboard-chunk.js" />
<link rel="modulepreload" href="/assets/vendor-react.js" />

<!-- Prefetch for likely next navigation -->
<link rel="prefetch" href="/assets/settings-chunk.js" />

Copy// Programmatic preloading
function preloadComponent(importFn: () => Promise<any>) {
  const link = document.createElement('link');
  link.rel = 'modulepreload';
  link.href = importFn.toString().match(/import\("(.+?)"\)/)?.[1] || '';
  document.head.appendChild(link);
}

7. Conditional Loading with Feature Flags

Copyimport { lazy, Suspense } from 'react';
import { useFeatureFlag } from '@/hooks/useFeatureFlag';

const NewDashboard = lazy(() => import('./NewDashboard'));
const LegacyDashboard = lazy(() => import('./LegacyDashboard'));

function Dashboard() {
  const useNewDashboard = useFeatureFlag('new-dashboard');

  return (
    <Suspense fallback={<DashboardSkeleton />}>
      {useNewDashboard ? <NewDashboard /> : <LegacyDashboard />}
    </Suspense>
  );
}

Suspense Boundaries Strategy

Copy// ✅ CORRECT: Granular Suspense boundaries
function Dashboard() {
  return (
    <div className="grid grid-cols-3 gap-4">
      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>
      <Suspense fallback={<ChartSkeleton />}>
        <UsersChart />
      </Suspense>
      <Suspense fallback={<TableSkeleton />}>
        <RecentOrders />
      </Suspense>
    </div>
  );
}

// ❌ WRONG: Single boundary blocks entire UI
function Dashboard() {
  return (
    <Suspense fallback={<FullPageSkeleton />}>
      <RevenueChart />
      <UsersChart />
      <RecentOrders />
    </Suspense>
  );
}

Error Boundaries with Lazy Components

Copyimport { Component, ErrorInfo, ReactNode } from 'react';

class LazyErrorBoundary extends Component<
  { children: ReactNode; fallback: ReactNode },
  { hasError: boolean }
> {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    console.error('Lazy load failed:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

// Usage
<LazyErrorBoundary fallback={<ErrorFallback />}>
  <Suspense fallback={<Skeleton />}>
    <LazyComponent />
  </Suspense>
</LazyErrorBoundary>

Bundle Analysis Integration

Copy// vite.config.ts
import { defineConfig } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // Vendor splitting
          'vendor-react': ['react', 'react-dom'],
          'vendor-router': ['react-router'],
          'vendor-query': ['@tanstack/react-query'],
          // Feature splitting
          'feature-charts': ['recharts', 'd3'],
          'feature-editor': ['@tiptap/react', '@tiptap/starter-kit'],
        },
      },
    },
  },
  plugins: [
    visualizer({
      filename: 'dist/bundle-analysis.html',
      open: true,
      gzipSize: true,
    }),
  ],
});

Performance Budgets

Copy// package.json
{
  "bundlesize": [
    { "path": "dist/assets/index-*.js", "maxSize": "80kb" },
    { "path": "dist/assets/vendor-react-*.js", "maxSize": "50kb" },
    { "path": "dist/assets/feature-*-*.js", "maxSize": "100kb" }
  ]
}

Anti-Patterns (FORBIDDEN)

Copy// ❌ NEVER: Lazy load small components (< 5KB)
const Button = lazy(() => import('./Button')); // Overhead > savings

// ❌ NEVER: Missing Suspense boundary
function App() {
  const Chart = lazy(() => import('./Chart'));
  return <Chart />; // Will throw!
}

// ❌ NEVER: Lazy inside render (creates new component each render)
function App() {
  const Component = lazy(() => import('./Component')); // ❌
  return <Component />;
}

// ❌ NEVER: Lazy loading critical above-fold content
const Hero = lazy(() => import('./Hero')); // Delays LCP!

// ❌ NEVER: Over-splitting (too many small chunks)
// Each chunk = 1 HTTP request = latency overhead

// ❌ NEVER: Missing error boundary for network failures
<Suspense fallback={<Skeleton />}>
  <LazyComponent /> {/* What if import fails? */}
</Suspense>

Key Decisions

Related Skills

• core-web-vitals - LCP optimization through lazy loading
• vite-advanced - Vite code splitting configuration
• render-optimization - React render performance
• react-server-components-framework - Server-side code splitting

Capability Details

component-lazy-loading

Keywords: React.lazy, dynamic import, Suspense, code splitting Solves: How to lazy load React components, reduce bundle size

route-splitting

Keywords: route, code splitting, React Router, lazy routes Solves: Route-based code splitting, per-page bundles

intersection-observer

Keywords: scroll, viewport, lazy, IntersectionObserver, below-fold Solves: Load components when scrolled into view

suspense-patterns

Keywords: Suspense, fallback, boundary, skeleton, loading Solves: Proper Suspense boundary placement, skeleton loading

preloading

Keywords: prefetch, preload, modulepreload, hover, intent Solves: Preload on hover, prefetch likely navigation

bundle-optimization

Keywords: bundle, chunks, splitting, manualChunks, vendor Solves: Optimize bundle splitting strategy, vendor chunks

References

• references/route-splitting.md - Route-based code splitting patterns
• references/intersection-observer.md - Scroll-triggered lazy loading
• scripts/lazy-component.tsx - Lazy component template