React Suspense Guide

React Suspense lets you declaratively handle loading states for async operations. Here's how to use it.

Basic Suspense#

import { Suspense, lazy } from 'react';

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

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

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

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

Nested Suspense#

// Different loading states for different sections
function App() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Header />
      <main>
        <Suspense fallback={<SidebarSkeleton />}>
          <Sidebar />
        </Suspense>
        <Suspense fallback={<ContentSkeleton />}>
          <Content />
        </Suspense>
      </main>
    </Suspense>
  );
}

// Cascading loading
function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<ChartSkeleton />}>
        <Charts />
        <Suspense fallback={<TableSkeleton />}>
          <DataTable />
        </Suspense>
      </Suspense>
    </div>
  );
}

Loading Fallbacks#

// Simple spinner
function LoadingSpinner() {
  return (
    <div className="spinner-container">
      <div className="spinner" />
    </div>
  );
}

// Skeleton loader
function CardSkeleton() {
  return (
    <div className="card skeleton">
      <div className="skeleton-image" />
      <div className="skeleton-title" />
      <div className="skeleton-text" />
      <div className="skeleton-text short" />
    </div>
  );
}

// Progress indicator
function LoadingProgress({ message = 'Loading...' }) {
  return (
    <div className="loading-progress">
      <div className="progress-bar">
        <div className="progress-fill" />
      </div>
      <p>{message}</p>
    </div>
  );
}

// Contextual loading
function TableLoadingState() {
  return (
    <table className="loading-table">
      <thead>
        <tr>
          <th><div className="skeleton-cell" /></th>
          <th><div className="skeleton-cell" /></th>
          <th><div className="skeleton-cell" /></th>
        </tr>
      </thead>
      <tbody>
        {Array.from({ length: 5 }).map((_, i) => (
          <tr key={i}>
            <td><div className="skeleton-cell" /></td>
            <td><div className="skeleton-cell" /></td>
            <td><div className="skeleton-cell" /></td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Error Boundaries with Suspense#

import { Component, Suspense } from 'react';

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

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

  componentDidCatch(error, errorInfo) {
    console.error('Error caught:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-container">
          <h2>Something went wrong</h2>
          <p>{this.state.error?.message}</p>
          <button onClick={() => this.setState({ hasError: false })}>
            Try again
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

// Usage
function App() {
  return (
    <ErrorBoundary>
      <Suspense fallback={<Loading />}>
        <AsyncComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

// Reusable wrapper
function AsyncBoundary({ children, fallback, errorFallback }) {
  return (
    <ErrorBoundary fallback={errorFallback}>
      <Suspense fallback={fallback}>
        {children}
      </Suspense>
    </ErrorBoundary>
  );
}

Data Fetching with Suspense#

// Simple cache for demonstration
const cache = new Map();

function fetchData(url) {
  if (!cache.has(url)) {
    cache.set(url, fetchWithSuspense(url));
  }
  return cache.get(url);
}

function fetchWithSuspense(url) {
  let status = 'pending';
  let result;

  const promise = fetch(url)
    .then(res => res.json())
    .then(data => {
      status = 'success';
      result = data;
    })
    .catch(error => {
      status = 'error';
      result = error;
    });

  return {
    read() {
      if (status === 'pending') throw promise;
      if (status === 'error') throw result;
      return result;
    }
  };
}

// Component that reads data
function UserProfile({ userId }) {
  const data = fetchData(`/api/users/${userId}`);
  const user = data.read(); // Suspends if pending

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

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

SuspenseList (Experimental)#

import { Suspense, SuspenseList } from 'react';

// Control reveal order of multiple suspense boundaries
function Feed() {
  return (
    <SuspenseList revealOrder="forwards" tail="collapsed">
      <Suspense fallback={<PostSkeleton />}>
        <Post id={1} />
      </Suspense>
      <Suspense fallback={<PostSkeleton />}>
        <Post id={2} />
      </Suspense>
      <Suspense fallback={<PostSkeleton />}>
        <Post id={3} />
      </Suspense>
    </SuspenseList>
  );
}

// revealOrder options:
// - "forwards": reveal in order, top to bottom
// - "backwards": reveal in order, bottom to top
// - "together": reveal all at once when all ready

// tail options:
// - "collapsed": show one fallback at a time
// - "hidden": show no fallbacks for unrevealed items

Transitions with Suspense#

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

function TabContainer() {
  const [tab, setTab] = useState('home');
  const [isPending, startTransition] = useTransition();

  function selectTab(nextTab) {
    startTransition(() => {
      setTab(nextTab);
    });
  }

  return (
    <div>
      <nav style={{ opacity: isPending ? 0.7 : 1 }}>
        <button onClick={() => selectTab('home')}>Home</button>
        <button onClick={() => selectTab('posts')}>Posts</button>
        <button onClick={() => selectTab('contact')}>Contact</button>
      </nav>
      <Suspense fallback={<TabSkeleton />}>
        <TabContent tab={tab} />
      </Suspense>
    </div>
  );
}

// Keep showing old content while loading new
function TabContent({ tab }) {
  const data = fetchTabData(tab);
  const content = data.read();

  return <div>{content}</div>;
}

useDeferredValue#

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

function SearchResults() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  const isStale = query !== deferredQuery;

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      <Suspense fallback={<SearchSkeleton />}>
        <div style={{ opacity: isStale ? 0.7 : 1 }}>
          <Results query={deferredQuery} />
        </div>
      </Suspense>
    </div>
  );
}

function Results({ query }) {
  const data = fetchSearchResults(query);
  const results = data.read();

  return (
    <ul>
      {results.map(item => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
}

Route-based Code Splitting#

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

// Lazy load routes
const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Products = lazy(() => import('./pages/Products'));
const ProductDetail = lazy(() => import('./pages/ProductDetail'));

function App() {
  return (
    <BrowserRouter>
      <Layout>
        <Suspense fallback={<PageLoader />}>
          <Routes>
            <Route path="/" element={<Home />} />
            <Route path="/about" element={<About />} />
            <Route path="/products" element={<Products />} />
            <Route path="/products/:id" element={<ProductDetail />} />
          </Routes>
        </Suspense>
      </Layout>
    </BrowserRouter>
  );
}

// Preload on hover
const ProductsPage = lazy(() => import('./pages/Products'));

function preloadProducts() {
  import('./pages/Products');
}

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link
        to="/products"
        onMouseEnter={preloadProducts}
        onFocus={preloadProducts}
      >
        Products
      </Link>
    </nav>
  );
}

Best Practices#

Fallback Design:
✓ Match fallback to content shape
✓ Use skeleton screens for better UX
✓ Keep fallbacks lightweight
✓ Avoid layout shifts

Boundaries:
✓ Place near async content
✓ Use nested Suspense for granularity
✓ Combine with Error Boundaries
✓ Consider user experience flow

Performance:
✓ Preload critical paths
✓ Use transitions for navigation
✓ Avoid waterfall loading
✓ Cache fetched data

Avoid:
✗ Suspense boundary too high
✗ Missing error handling
✗ Flash of loading states
✗ Over-splitting code

React Suspense provides a declarative way to handle loading states. Use it with lazy loading for code splitting, combine with Error Boundaries for robust error handling, and leverage transitions for smooth navigation. Design fallbacks that match your content structure to minimize layout shifts.