React Suspense Boundaries Guide

React Suspense lets you declaratively specify loading states for components that are waiting for data or code to load.

Basic Usage#

import { Suspense, lazy } from 'react';

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

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

Code Splitting with lazy()#

import { Suspense, lazy } from 'react';

// Split by routes
const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard'));

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

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

// With preload
const HeavyChart = lazy(() => import('./HeavyChart'));

// Preload on hover
function ChartButton() {
  const handleMouseEnter = () => {
    import('./HeavyChart'); // Start loading
  };

  return (
    <button onMouseEnter={handleMouseEnter}>
      Show Chart
    </button>
  );
}

Nested Suspense Boundaries#

import { Suspense, lazy } from 'react';

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

function App() {
  return (
    <div className="app">
      {/* Outer boundary for layout */}
      <Suspense fallback={<LayoutSkeleton />}>
        <Header />

        <div className="body">
          <Sidebar />

          {/* Inner boundary for content */}
          <Suspense fallback={<ContentSkeleton />}>
            <MainContent />

            {/* Innermost for comments */}
            <Suspense fallback={<CommentsSkeleton />}>
              <Comments />
            </Suspense>
          </Suspense>
        </div>
      </Suspense>
    </div>
  );
}

Data Fetching with Suspense#

// With React Query / TanStack Query
import { useSuspenseQuery } from '@tanstack/react-query';

function UserProfile({ userId }) {
  // This suspends until data is ready
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId)
  });

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

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

// Multiple suspending components
function Dashboard() {
  return (
    <Suspense fallback={<DashboardSkeleton />}>
      <UserProfile />
      <UserStats />
      <RecentActivity />
    </Suspense>
  );
}

Suspense with Error Boundaries#

import { Suspense, Component } from 'react';

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

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

  render() {
    if (this.state.hasError) {
      return this.props.fallback || <div>Something went wrong</div>;
    }
    return this.props.children;
  }
}

// Combine Error Boundary and Suspense
function AsyncBoundary({ children, errorFallback, loadingFallback }) {
  return (
    <ErrorBoundary fallback={errorFallback}>
      <Suspense fallback={loadingFallback}>
        {children}
      </Suspense>
    </ErrorBoundary>
  );
}

// Usage
function App() {
  return (
    <AsyncBoundary
      loadingFallback={<Spinner />}
      errorFallback={<ErrorMessage />}
    >
      <DataComponent />
    </AsyncBoundary>
  );
}

Loading States and Skeletons#

// Skeleton components
function ProfileSkeleton() {
  return (
    <div className="profile-skeleton">
      <div className="skeleton avatar" />
      <div className="skeleton name" />
      <div className="skeleton bio" />
    </div>
  );
}

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>
  );
}

// Match skeleton to component structure
function PostList() {
  const { data: posts } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts
  });

  return (
    <div className="post-list">
      {posts.map(post => (
        <PostCard key={post.id} post={post} />
      ))}
    </div>
  );
}

function PostListSkeleton() {
  return (
    <div className="post-list">
      {[1, 2, 3].map(i => (
        <CardSkeleton key={i} />
      ))}
    </div>
  );
}

// In parent
<Suspense fallback={<PostListSkeleton />}>
  <PostList />
</Suspense>

SuspenseList (Experimental)#

import { Suspense, SuspenseList } from 'react';

// Control reveal order
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 reverse order
// - 'together': reveal all at once when ready

// tail options:
// - 'collapsed': only show one fallback at a time
// - 'hidden': don't show fallbacks for items not yet revealed

useTransition for Non-Blocking Updates#

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('settings')}>Settings</button>
      </nav>

      <Suspense fallback={<TabSkeleton />}>
        {tab === 'home' && <Home />}
        {tab === 'posts' && <Posts />}
        {tab === 'settings' && <Settings />}
      </Suspense>
    </div>
  );
}

useDeferredValue#

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

function SearchResults({ query }) {
  const { data } = useSuspenseQuery({
    queryKey: ['search', query],
    queryFn: () => search(query)
  });

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

const MemoizedResults = memo(SearchResults);

function SearchPage() {
  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={<ResultsSkeleton />}>
        <div style={{ opacity: isStale ? 0.7 : 1 }}>
          <MemoizedResults query={deferredQuery} />
        </div>
      </Suspense>
    </div>
  );
}

Server Components with Suspense#

// Server Component (Next.js App Router)
async function UserProfile({ userId }) {
  const user = await fetchUser(userId);

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

// Page with Suspense
export default function Page({ params }) {
  return (
    <div>
      <h1>Dashboard</h1>

      <Suspense fallback={<ProfileSkeleton />}>
        <UserProfile userId={params.id} />
      </Suspense>

      <Suspense fallback={<StatsSkeleton />}>
        <UserStats userId={params.id} />
      </Suspense>
    </div>
  );
}

// Streaming with loading.js (Next.js)
// app/dashboard/loading.js
export default function Loading() {
  return <DashboardSkeleton />;
}

Custom Suspense-Compatible Resources#

// Create suspense-compatible resource
function createResource(promise) {
  let status = 'pending';
  let result;

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

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

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

function UserProfile() {
  const user = userResource.read(); // Suspends if pending

  return <div>{user.name}</div>;
}

// Wrapper component
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <UserProfile />
    </Suspense>
  );
}

Loading Priority Patterns#

// Critical content loads first
function ProductPage({ productId }) {
  return (
    <div>
      {/* Critical - no suspense, or high priority */}
      <ProductHeader productId={productId} />

      {/* Important - medium priority */}
      <Suspense fallback={<PriceSkeleton />}>
        <ProductPrice productId={productId} />
      </Suspense>

      {/* Can wait - low priority */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={productId} />
      </Suspense>

      {/* Lazy load when visible */}
      <LazySection>
        <Suspense fallback={<RecommendationsSkeleton />}>
          <Recommendations productId={productId} />
        </Suspense>
      </LazySection>
    </div>
  );
}

// Intersection Observer for lazy loading
function LazySection({ children }) {
  const [isVisible, setIsVisible] = useState(false);
  const ref = useRef();

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

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

  return <div ref={ref}>{isVisible ? children : null}</div>;
}

Best Practices#

Boundary Placement:
✓ Place at route level for pages
✓ Use nested boundaries for sections
✓ Match skeletons to component structure
✓ Consider user experience

Loading States:
✓ Use meaningful skeletons
✓ Avoid layout shifts
✓ Show progress when possible
✓ Keep fallbacks lightweight

Performance:
✓ Preload critical resources
✓ Use useTransition for navigation
✓ Defer non-critical updates
✓ Code split by routes

Avoid:
✗ Too many suspense boundaries
✗ Flashing loading states
✗ Blocking critical content
✗ Forgetting error boundaries

React Suspense provides declarative loading states for async operations. Use it with lazy() for code splitting, with data fetching libraries for loading states, and with useTransition for smooth transitions. Place Suspense boundaries strategically to control loading experiences. Combine with Error Boundaries for comprehensive async handling. Match skeleton components to actual content structure to prevent layout shifts and provide better user experience.