React Lazy Loading Patterns

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

React.lazy Basics#

import { lazy, Suspense } from 'react';

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

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <HeavyComponent />
    </Suspense>
  );
}

// Named exports
const Dashboard = lazy(() =>
  import('./Dashboard').then(module => ({
    default: module.Dashboard,
  }))
);

// With error boundary
import { ErrorBoundary } from 'react-error-boundary';

function AppWithError() {
  return (
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <HeavyComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

Route-Based Code Splitting#

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

// Lazy load routes
const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));
const Profile = lazy(() => import('./pages/Profile'));

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

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

// With layout
const DashboardLayout = lazy(() => import('./layouts/DashboardLayout'));
const Analytics = lazy(() => import('./pages/Analytics'));
const Reports = lazy(() => import('./pages/Reports'));

function AppWithLayout() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/dashboard" element={<DashboardLayout />}>
          <Route index element={<Analytics />} />
          <Route path="reports" element={<Reports />} />
        </Route>
      </Routes>
    </Suspense>
  );
}

Preloading Components#

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

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

// Preload on hover
function NavLink({ to, children, component }: {
  to: string;
  children: React.ReactNode;
  component: { preload?: () => Promise<any> };
}) {
  const handleMouseEnter = () => {
    component.preload?.();
  };

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

// Usage
function Navigation() {
  return (
    <nav>
      <NavLink to="/dashboard" component={Dashboard}>
        Dashboard
      </NavLink>
      <NavLink to="/settings" component={Settings}>
        Settings
      </NavLink>
    </nav>
  );
}

// Preload on route change intent
function usePreloadOnIntent(path: string, component: { preload?: () => Promise<any> }) {
  const location = useLocation();

  useEffect(() => {
    // Preload when user might navigate
    if (location.pathname.startsWith('/dashboard')) {
      component.preload?.();
    }
  }, [location, component]);
}

Component-Level Lazy Loading#

// Lazy load modal content
const ModalContent = lazy(() => import('./ModalContent'));

function Modal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
  if (!isOpen) return null;

  return (
    <div className="modal">
      <Suspense fallback={<div>Loading...</div>}>
        <ModalContent onClose={onClose} />
      </Suspense>
    </div>
  );
}

// Lazy load tabs
const TabAnalytics = lazy(() => import('./tabs/Analytics'));
const TabUsers = lazy(() => import('./tabs/Users'));
const TabSettings = lazy(() => import('./tabs/Settings'));

function Tabs() {
  const [activeTab, setActiveTab] = useState('analytics');

  const tabs = {
    analytics: TabAnalytics,
    users: TabUsers,
    settings: TabSettings,
  };

  const ActiveComponent = tabs[activeTab];

  return (
    <div>
      <div className="tab-buttons">
        <button onClick={() => setActiveTab('analytics')}>Analytics</button>
        <button onClick={() => setActiveTab('users')}>Users</button>
        <button onClick={() => setActiveTab('settings')}>Settings</button>
      </div>
      <Suspense fallback={<TabSkeleton />}>
        <ActiveComponent />
      </Suspense>
    </div>
  );
}

Image Lazy Loading#

// Native lazy loading
function LazyImage({ src, alt, ...props }: React.ImgHTMLAttributes<HTMLImageElement>) {
  return <img src={src} alt={alt} loading="lazy" {...props} />;
}

// Intersection Observer approach
function useIntersection(
  ref: React.RefObject<Element>,
  options?: IntersectionObserverInit
) {
  const [isIntersecting, setIsIntersecting] = useState(false);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;

    const observer = new IntersectionObserver(([entry]) => {
      setIsIntersecting(entry.isIntersecting);
    }, options);

    observer.observe(element);
    return () => observer.disconnect();
  }, [ref, options]);

  return isIntersecting;
}

function LazyImageWithObserver({
  src,
  alt,
  placeholder = '/placeholder.jpg',
  ...props
}: {
  src: string;
  alt: string;
  placeholder?: string;
} & React.ImgHTMLAttributes<HTMLImageElement>) {
  const ref = useRef<HTMLDivElement>(null);
  const isVisible = useIntersection(ref, { rootMargin: '100px' });
  const [loaded, setLoaded] = useState(false);

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

// Progressive image loading
function ProgressiveImage({
  lowQualitySrc,
  highQualitySrc,
  alt,
}: {
  lowQualitySrc: string;
  highQualitySrc: string;
  alt: string;
}) {
  const [src, setSrc] = useState(lowQualitySrc);
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    const img = new Image();
    img.src = highQualitySrc;
    img.onload = () => {
      setSrc(highQualitySrc);
      setLoaded(true);
    };
  }, [highQualitySrc]);

  return (
    <img
      src={src}
      alt={alt}
      className={loaded ? 'loaded' : 'loading'}
      style={{
        filter: loaded ? 'none' : 'blur(10px)',
        transition: 'filter 0.3s',
      }}
    />
  );
}

List Virtualization#

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

function VirtualizedList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

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

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

Conditional Loading#

// Load based on feature flag
function FeatureFlag({ flag, children }: { flag: string; children: React.ReactNode }) {
  const [enabled, setEnabled] = useState(false);
  const [Component, setComponent] = useState<React.ComponentType | null>(null);

  useEffect(() => {
    checkFeatureFlag(flag).then((enabled) => {
      if (enabled) {
        setEnabled(true);
      }
    });
  }, [flag]);

  if (!enabled) return null;

  return <>{children}</>;
}

// Load based on user role
const AdminPanel = lazy(() => import('./AdminPanel'));

function ConditionalAdmin({ user }: { user: User }) {
  if (user.role !== 'admin') {
    return null;
  }

  return (
    <Suspense fallback={<div>Loading admin panel...</div>}>
      <AdminPanel />
    </Suspense>
  );
}

// Load based on viewport
function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(
    () => window.matchMedia(query).matches
  );

  useEffect(() => {
    const mq = window.matchMedia(query);
    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, [query]);

  return matches;
}

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

function ResponsiveLayout() {
  const isDesktop = useMediaQuery('(min-width: 1024px)');

  return (
    <div>
      {isDesktop && (
        <Suspense fallback={null}>
          <DesktopSidebar />
        </Suspense>
      )}
      <main>{/* Content */}</main>
    </div>
  );
}

Bundle Analysis#

// Webpack magic comments for naming
const Dashboard = lazy(() =>
  import(/* webpackChunkName: "dashboard" */ './Dashboard')
);

const Analytics = lazy(() =>
  import(
    /* webpackChunkName: "analytics" */
    /* webpackPrefetch: true */
    './Analytics'
  )
);

const Reports = lazy(() =>
  import(
    /* webpackChunkName: "reports" */
    /* webpackPreload: true */
    './Reports'
  )
);

// Group related components
const AdminPages = lazy(() =>
  import(/* webpackChunkName: "admin" */ './admin')
);

Loading States#

// Skeleton loader
function DashboardSkeleton() {
  return (
    <div className="dashboard-skeleton">
      <div className="skeleton-header" />
      <div className="skeleton-grid">
        {Array.from({ length: 6 }).map((_, i) => (
          <div key={i} className="skeleton-card" />
        ))}
      </div>
    </div>
  );
}

// Deferred loading state
function useDeferredLoading(delay = 200) {
  const [showLoading, setShowLoading] = useState(false);

  useEffect(() => {
    const timeout = setTimeout(() => setShowLoading(true), delay);
    return () => clearTimeout(timeout);
  }, [delay]);

  return showLoading;
}

function DeferredFallback({ delay = 200 }: { delay?: number }) {
  const showLoading = useDeferredLoading(delay);

  if (!showLoading) return null;
  return <Spinner />;
}

// Usage
function App() {
  return (
    <Suspense fallback={<DeferredFallback />}>
      <Dashboard />
    </Suspense>
  );
}

Error Recovery#

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

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

    throw lastError;
  });
}

const Dashboard = LazyComponentWithRetry(() => import('./Dashboard'));

Best Practices#

Code Splitting:
✓ Split at route level first
✓ Split large components
✓ Group related code in chunks
✓ Analyze bundle sizes

Loading UX:
✓ Use meaningful loading states
✓ Show skeletons over spinners
✓ Defer loading indicator display
✓ Preload on user intent

Performance:
✓ Set appropriate chunk sizes
✓ Use prefetch for likely routes
✓ Avoid over-splitting
✓ Monitor Core Web Vitals

Images:
✓ Use native loading="lazy"
✓ Provide width/height
✓ Use appropriate formats
✓ Consider progressive loading

Lazy loading improves initial load performance by deferring non-critical resources. Use route-based splitting for the biggest impact, preload on user intent for better UX, and always provide meaningful loading states. Monitor bundle sizes and Core Web Vitals to measure impact.