React Lazy Loading Components

React.lazy and Suspense enable code splitting for better performance. Here's how to use them effectively.

Basic Lazy Loading#

import { lazy, Suspense } from 'react';

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

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

// Without lazy loading - bundled immediately
// import HeavyComponent from './HeavyComponent';

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 Settings = lazy(() => import('./pages/Settings'));

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

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

Multiple Suspense Boundaries#

import { lazy, Suspense } from 'react';

const Header = lazy(() => import('./Header'));
const Sidebar = lazy(() => import('./Sidebar'));
const MainContent = lazy(() => import('./MainContent'));
const Footer = lazy(() => import('./Footer'));

function App() {
  return (
    <div className="app">
      {/* Critical - load first */}
      <Suspense fallback={<HeaderSkeleton />}>
        <Header />
      </Suspense>

      <div className="content">
        {/* Non-critical - can load independently */}
        <Suspense fallback={<SidebarSkeleton />}>
          <Sidebar />
        </Suspense>

        <Suspense fallback={<ContentSkeleton />}>
          <MainContent />
        </Suspense>
      </div>

      <Suspense fallback={null}>
        <Footer />
      </Suspense>
    </div>
  );
}

Named Exports#

// Component file with named export
// components/Charts.js
export const LineChart = () => { /* ... */ };
export const BarChart = () => { /* ... */ };
export const PieChart = () => { /* ... */ };

// Lazy loading named exports
const LineChart = lazy(() =>
  import('./components/Charts').then(module => ({
    default: module.LineChart
  }))
);

const BarChart = lazy(() =>
  import('./components/Charts').then(module => ({
    default: module.BarChart
  }))
);

// Or create a wrapper
// chartLoaders.js
export const LazyLineChart = lazy(() =>
  import('./Charts').then(m => ({ default: m.LineChart }))
);

Preloading Components#

import { lazy, Suspense } from 'react';

// Create lazy component
const HeavyFeature = lazy(() => import('./HeavyFeature'));

// Preload function
const preloadHeavyFeature = () => import('./HeavyFeature');

function App() {
  return (
    <div>
      {/* Preload on hover */}
      <button
        onMouseEnter={preloadHeavyFeature}
        onClick={() => setShowFeature(true)}
      >
        Show Feature
      </button>

      {showFeature && (
        <Suspense fallback={<Loading />}>
          <HeavyFeature />
        </Suspense>
      )}
    </div>
  );
}

// Preload on route link hover
function NavLink({ to, children, component }) {
  const preload = () => {
    if (component) {
      component.preload?.();
    }
  };

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

Error Handling#

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

// Error Boundary
class ErrorBoundary extends Component {
  state = { hasError: false, error: null };

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

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

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

// Wrap lazy components
function App() {
  return (
    <ErrorBoundary>
      <Suspense fallback={<Loading />}>
        <LazyComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

// Retry logic with lazy
function lazyWithRetry(importFn, retries = 3) {
  return lazy(async () => {
    for (let i = 0; i < retries; i++) {
      try {
        return await importFn();
      } catch (error) {
        if (i === retries - 1) throw error;
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
      }
    }
  });
}

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

Conditional Loading#

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

// Only load when needed
const AdminPanel = lazy(() => import('./AdminPanel'));
const UserPanel = lazy(() => import('./UserPanel'));

function Dashboard({ user }) {
  return (
    <Suspense fallback={<DashboardSkeleton />}>
      {user.isAdmin ? <AdminPanel /> : <UserPanel />}
    </Suspense>
  );
}

// Feature flag loading
const NewFeature = lazy(() => import('./NewFeature'));
const LegacyFeature = lazy(() => import('./LegacyFeature'));

function Feature({ flags }) {
  const Component = flags.newFeature ? NewFeature : LegacyFeature;

  return (
    <Suspense fallback={<Loading />}>
      <Component />
    </Suspense>
  );
}

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

// Heavy modal loaded on demand
const SettingsModal = lazy(() => import('./SettingsModal'));

function App() {
  const [showSettings, setShowSettings] = useState(false);

  return (
    <div>
      <button onClick={() => setShowSettings(true)}>
        Open Settings
      </button>

      {showSettings && (
        <Suspense fallback={<ModalLoader />}>
          <SettingsModal onClose={() => setShowSettings(false)} />
        </Suspense>
      )}
    </div>
  );
}

// Preload pattern for modals
const preloadSettingsModal = () => import('./SettingsModal');

function SettingsButton() {
  return (
    <button
      onMouseEnter={preloadSettingsModal}
      onFocus={preloadSettingsModal}
      onClick={() => setShowSettings(true)}
    >
      Settings
    </button>
  );
}

Skeleton Loading#

import { lazy, Suspense } from 'react';

// Skeleton component matching content shape
function CardSkeleton() {
  return (
    <div className="card skeleton">
      <div className="skeleton-image" />
      <div className="skeleton-text" />
      <div className="skeleton-text short" />
    </div>
  );
}

function CardListSkeleton({ count = 3 }) {
  return (
    <div className="card-list">
      {Array.from({ length: count }, (_, i) => (
        <CardSkeleton key={i} />
      ))}
    </div>
  );
}

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

function Dashboard() {
  return (
    <Suspense fallback={<CardListSkeleton count={6} />}>
      <CardList />
    </Suspense>
  );
}

Code Splitting Strategies#

// 1. Route-based (most common)
const routes = {
  '/': lazy(() => import('./pages/Home')),
  '/about': lazy(() => import('./pages/About')),
};

// 2. Component-based (large components)
const RichTextEditor = lazy(() => import('./RichTextEditor'));
const DataVisualization = lazy(() => import('./DataVisualization'));

// 3. Feature-based (feature flags)
const BetaFeature = lazy(() => import('./features/BetaFeature'));

// 4. Vendor splitting (heavy libraries)
const ChartWithD3 = lazy(() => import('./ChartWithD3'));
// This creates separate chunk with d3 included

// 5. Below-the-fold content
const BelowFold = lazy(() => import('./BelowFoldContent'));

function Page() {
  return (
    <>
      <AboveFoldContent />
      <Suspense fallback={null}>
        <BelowFold />
      </Suspense>
    </>
  );
}

Webpack Magic Comments#

// Named chunks
const Component = lazy(() =>
  import(/* webpackChunkName: "feature-a" */ './FeatureA')
);

// Prefetch (load in idle time)
const Component = lazy(() =>
  import(/* webpackPrefetch: true */ './HeavyComponent')
);

// Preload (load with parent)
const Component = lazy(() =>
  import(/* webpackPreload: true */ './CriticalComponent')
);

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

Testing Lazy Components#

import { render, screen, waitFor } from '@testing-library/react';
import { Suspense } from 'react';

// Mock the lazy import
jest.mock('./HeavyComponent', () => ({
  __esModule: true,
  default: () => <div>Heavy Component Content</div>,
}));

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

test('renders lazy component', async () => {
  render(
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );

  // Initially shows fallback
  expect(screen.getByText('Loading...')).toBeInTheDocument();

  // Wait for component to load
  await waitFor(() => {
    expect(screen.getByText('Heavy Component Content')).toBeInTheDocument();
  });
});

Best Practices#

When to Use:
✓ Route components
✓ Large components (>30KB)
✓ Conditionally rendered content
✓ Below-the-fold content

Suspense Boundaries:
✓ Group related components
✓ Place near lazy components
✓ Provide meaningful fallbacks
✓ Consider UX of loading states

Performance:
✓ Preload on hover/focus
✓ Use webpackPrefetch
✓ Combine related chunks
✓ Measure bundle sizes

Avoid:
✗ Over-splitting small components
✗ Single global Suspense
✗ Ignoring error boundaries
✗ Too many loading states

React.lazy and Suspense enable powerful code splitting for better initial load times. Use route-based splitting for page components, lazy load heavy components and modals, and provide meaningful loading states. Preload components on user interaction hints for better perceived performance. Always wrap lazy components with error boundaries for production reliability.