React Lazy Loading Guide

Lazy loading improves initial load times by deferring non-critical resources. Here's how to implement it effectively.

React.lazy Basics#

import { lazy, Suspense } from 'react';

// Lazy load a component
const HeavyComponent = lazy(() => import('./HeavyComponent'));

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <HeavyComponent />
    </Suspense>
  );
}

// With named exports
const MyComponent = lazy(() =>
  import('./MyModule').then(module => ({
    default: module.MyComponent,
  }))
);

// Multiple lazy components
const Dashboard = lazy(() => import('./Dashboard'));
const Settings = lazy(() => import('./Settings'));
const Profile = lazy(() => import('./Profile'));

function App() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
        <Route path="/profile" element={<Profile />} />
      </Routes>
    </Suspense>
  );
}

Route-Based Code Splitting#

import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// Lazy load route components
const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const NotFound = lazy(() => import('./pages/NotFound'));

// Loading component
function PageLoader() {
  return (
    <div className="page-loader">
      <div className="spinner" />
      <p>Loading...</p>
    </div>
  );
}

function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<PageLoader />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/dashboard/*" element={<Dashboard />} />
          <Route path="*" element={<NotFound />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

// Nested route splitting
const DashboardOverview = lazy(() => import('./pages/DashboardOverview'));
const DashboardAnalytics = lazy(() => import('./pages/DashboardAnalytics'));
const DashboardSettings = lazy(() => import('./pages/DashboardSettings'));

function Dashboard() {
  return (
    <div className="dashboard">
      <Sidebar />
      <Suspense fallback={<ContentLoader />}>
        <Routes>
          <Route index element={<DashboardOverview />} />
          <Route path="analytics" element={<DashboardAnalytics />} />
          <Route path="settings" element={<DashboardSettings />} />
        </Routes>
      </Suspense>
    </div>
  );
}

Component-Level Splitting#

import { lazy, Suspense, useState } from 'react';

// Lazy load heavy components
const DataVisualization = lazy(() => import('./DataVisualization'));
const RichTextEditor = lazy(() => import('./RichTextEditor'));
const ImageEditor = lazy(() => import('./ImageEditor'));

function App() {
  const [showEditor, setShowEditor] = useState(false);

  return (
    <div>
      <button onClick={() => setShowEditor(true)}>Open Editor</button>

      {showEditor && (
        <Suspense fallback={<EditorSkeleton />}>
          <RichTextEditor />
        </Suspense>
      )}
    </div>
  );
}

// Modal with lazy content
const ModalContent = lazy(() => import('./ModalContent'));

function Modal({ isOpen, onClose }) {
  if (!isOpen) return null;

  return (
    <div className="modal-overlay">
      <div className="modal">
        <Suspense fallback={<ModalLoader />}>
          <ModalContent onClose={onClose} />
        </Suspense>
      </div>
    </div>
  );
}

Preloading Components#

// Preload function
const Dashboard = lazy(() => import('./Dashboard'));

// Preload on hover
function NavLink({ to, children }) {
  const preload = () => {
    if (to === '/dashboard') {
      import('./Dashboard');
    }
  };

  return (
    <Link to={to} onMouseEnter={preload}>
      {children}
    </Link>
  );
}

// Preload factory
function lazyWithPreload<T extends React.ComponentType<any>>(
  factory: () => Promise<{ default: T }>
) {
  const Component = lazy(factory);
  (Component as any).preload = factory;
  return Component;
}

const Settings = lazyWithPreload(() => import('./Settings'));

// Usage
function Nav() {
  return (
    <nav>
      <Link
        to="/settings"
        onMouseEnter={() => (Settings as any).preload()}
      >
        Settings
      </Link>
    </nav>
  );
}

// Preload on route change
import { useLocation } from 'react-router-dom';

function usePreloadOnRouteChange() {
  const location = useLocation();

  useEffect(() => {
    // Preload likely next routes
    if (location.pathname === '/') {
      import('./Dashboard');
    } else if (location.pathname === '/dashboard') {
      import('./Settings');
    }
  }, [location.pathname]);
}

Lazy Loading Images#

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

// Intersection Observer hook
function useLazyLoad() {
  const [isVisible, setIsVisible] = useState(false);
  const ref = useRef<HTMLDivElement>(null);

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

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

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

  return { ref, isVisible };
}

// Lazy image component
function LazyImage({ src, alt, placeholder, ...props }) {
  const { ref, isVisible } = useLazyLoad();
  const [loaded, setLoaded] = useState(false);

  return (
    <div ref={ref} className="lazy-image-container">
      {placeholder && !loaded && (
        <img src={placeholder} alt="" className="placeholder" />
      )}
      {isVisible && (
        <img
          src={src}
          alt={alt}
          onLoad={() => setLoaded(true)}
          className={loaded ? 'loaded' : 'loading'}
          {...props}
        />
      )}
    </div>
  );
}

// Native lazy loading
function NativelazyImage({ src, alt, ...props }) {
  return <img src={src} alt={alt} loading="lazy" {...props} />;
}

// Image gallery with lazy loading
function ImageGallery({ images }) {
  return (
    <div className="gallery">
      {images.map((image) => (
        <LazyImage
          key={image.id}
          src={image.url}
          alt={image.alt}
          placeholder={image.thumbnail}
        />
      ))}
    </div>
  );
}

Lazy Loading Data#

import { Suspense, use } from 'react';

// Data fetching with Suspense
function createResource<T>(promise: Promise<T>) {
  let status = 'pending';
  let result: T;

  const suspender = promise.then(
    (data) => {
      status = 'success';
      result = data;
    },
    (error) => {
      status = 'error';
      result = error;
    }
  );

  return {
    read(): T {
      if (status === 'pending') throw suspender;
      if (status === 'error') throw result;
      return result;
    },
  };
}

// Usage
const userResource = createResource(fetchUser());

function UserProfile() {
  const user = userResource.read();
  return <div>{user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<ProfileSkeleton />}>
      <UserProfile />
    </Suspense>
  );
}

// React 19 use() hook
async function fetchPosts(): Promise<Post[]> {
  const response = await fetch('/api/posts');
  return response.json();
}

function PostList({ postsPromise }: { postsPromise: Promise<Post[]> }) {
  const posts = use(postsPromise);
  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Skeleton Loading#

// Skeleton components
function SkeletonText({ width = '100%' }) {
  return <div className="skeleton-text" style={{ width }} />;
}

function SkeletonCircle({ size = 40 }) {
  return (
    <div
      className="skeleton-circle"
      style={{ width: size, height: size }}
    />
  );
}

function SkeletonRect({ width = '100%', height = 100 }) {
  return (
    <div
      className="skeleton-rect"
      style={{ width, height }}
    />
  );
}

// Page skeleton
function DashboardSkeleton() {
  return (
    <div className="dashboard-skeleton">
      <div className="header">
        <SkeletonCircle size={32} />
        <SkeletonText width="150px" />
      </div>
      <div className="cards">
        {[1, 2, 3].map(i => (
          <SkeletonRect key={i} height={200} />
        ))}
      </div>
    </div>
  );
}

// CSS
const skeletonStyles = `
.skeleton-text,
.skeleton-circle,
.skeleton-rect {
  background: linear-gradient(
    90deg,
    #f0f0f0 25%,
    #e0e0e0 50%,
    #f0f0f0 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

@keyframes shimmer {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

.skeleton-text {
  height: 1em;
  border-radius: 4px;
}

.skeleton-circle {
  border-radius: 50%;
}

.skeleton-rect {
  border-radius: 8px;
}
`;

Error Boundaries#

import { Component, lazy, Suspense } from 'react';

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

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

  retry = () => {
    this.setState({ hasError: false });
  };

  render() {
    if (this.state.hasError) {
      return (
        <div>
          <p>Failed to load component</p>
          <button onClick={this.retry}>Retry</button>
        </div>
      );
    }
    return this.props.children;
  }
}

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

function App() {
  return (
    <LazyErrorBoundary fallback={<ErrorMessage />}>
      <Suspense fallback={<Loader />}>
        <HeavyComponent />
      </Suspense>
    </LazyErrorBoundary>
  );
}

// Retry lazy import
function lazyWithRetry<T extends React.ComponentType<any>>(
  factory: () => Promise<{ default: T }>,
  retries = 3
) {
  return lazy(async () => {
    let lastError: Error | undefined;

    for (let i = 0; i < retries; i++) {
      try {
        return await factory();
      } catch (error) {
        lastError = error as Error;
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
      }
    }

    throw lastError;
  });
}

const ReliableComponent = lazyWithRetry(() => import('./Component'));

Virtualized Lists#

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

function VirtualList({ items }) {
  const parentRef = useRef<HTMLDivElement>(null);

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

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

Best Practices#

Component Splitting:
✓ Split by route
✓ Split heavy/rarely-used components
✓ Preload on user interaction
✓ Use meaningful chunk names

Loading States:
✓ Show skeleton loaders
✓ Keep layout stable
✓ Avoid flash of loading
✓ Handle errors gracefully

Images:
✓ Use native loading="lazy"
✓ Provide placeholders
✓ Use Intersection Observer
✓ Optimize image sizes

Performance:
✓ Measure with DevTools
✓ Set appropriate chunk sizes
✓ Preload critical resources
✓ Test on slow networks

Lazy loading is essential for fast initial page loads. Use React.lazy for components, route-based splitting for pages, and Intersection Observer for images. Combine with proper loading states and error handling for a smooth user experience.