React Suspense Boundaries

Suspense handles async operations with declarative loading states. Here's how to use it effectively.

Basic Suspense#

import { Suspense } from 'react';

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

function Loading() {
  return <div className="spinner">Loading...</div>;
}

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

function App() {
  return (
    <Suspense fallback={<Skeleton />}>
      <LazyComponent />
    </Suspense>
  );
}

Nested Suspense Boundaries#

function Dashboard() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Header />

      <main>
        {/* Independent loading states */}
        <Suspense fallback={<ChartSkeleton />}>
          <Charts />
        </Suspense>

        <Suspense fallback={<TableSkeleton />}>
          <DataTable />
        </Suspense>

        <Suspense fallback={<ActivitySkeleton />}>
          <RecentActivity />
        </Suspense>
      </main>
    </Suspense>
  );
}

// Each section loads independently
// Fast sections appear first

Suspense with Data Fetching#

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

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });

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

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

// Using SWR
import useSWR from 'swr';

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSWR(`/api/users/${userId}`, fetcher, {
    suspense: true,
  });

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

Error Boundaries with Suspense#

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

function App() {
  return (
    <ErrorBoundary
      fallback={<ErrorMessage />}
      onError={(error) => logError(error)}
    >
      <Suspense fallback={<Loading />}>
        <AsyncContent />
      </Suspense>
    </ErrorBoundary>
  );
}

// Combined error and loading states
function AsyncSection({ children }: { children: React.ReactNode }) {
  return (
    <ErrorBoundary
      fallback={({ error, resetErrorBoundary }) => (
        <div className="error">
          <p>Error: {error.message}</p>
          <button onClick={resetErrorBoundary}>Retry</button>
        </div>
      )}
    >
      <Suspense fallback={<SectionSkeleton />}>
        {children}
      </Suspense>
    </ErrorBoundary>
  );
}

function Dashboard() {
  return (
    <div>
      <AsyncSection>
        <UserStats />
      </AsyncSection>

      <AsyncSection>
        <RecentOrders />
      </AsyncSection>
    </div>
  );
}

Streaming SSR with Suspense#

// Next.js App Router
// app/page.tsx
import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Static content renders immediately */}
      <StaticHeader />

      {/* Async content streams in */}
      <Suspense fallback={<UserSkeleton />}>
        <UserInfo />
      </Suspense>

      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>
    </div>
  );
}

// Server component with async data
async function UserInfo() {
  const user = await fetchUser();
  return <div>{user.name}</div>;
}

async function Stats() {
  const stats = await fetchStats();
  return (
    <div>
      <p>Total: {stats.total}</p>
    </div>
  );
}

SuspenseList (Experimental)#

import { SuspenseList, Suspense } from 'react';

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": Top to bottom
// - "backwards": Bottom to top
// - "together": All at once

// tail options:
// - "collapsed": Show one fallback at a time
// - "hidden": Don't show fallbacks

Transitions with Suspense#

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

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

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

  return (
    <div>
      <nav style={{ opacity: isPending ? 0.7 : 1 }}>
        <button onClick={() => selectTab('home')}>Home</button>
        <button onClick={() => selectTab('profile')}>Profile</button>
        <button onClick={() => selectTab('settings')}>Settings</button>
      </nav>

      <Suspense fallback={<TabSkeleton />}>
        {tab === 'home' && <HomeTab />}
        {tab === 'profile' && <ProfileTab />}
        {tab === 'settings' && <SettingsTab />}
      </Suspense>
    </div>
  );
}

Deferred Values#

import { useDeferredValue, Suspense, useState } 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..."
      />

      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <Suspense fallback={<ResultsSkeleton />}>
          <Results query={deferredQuery} />
        </Suspense>
      </div>
    </div>
  );
}

// Results component can suspend
function Results({ query }: { query: string }) {
  const results = use(fetchResults(query));

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

Custom Suspense Hook#

// Create suspense-enabled resource
function createResource<T>(promise: Promise<T>) {
  let status: 'pending' | 'success' | 'error' = 'pending';
  let result: T;
  let error: Error;

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

  return {
    read(): T {
      switch (status) {
        case 'pending':
          throw suspender;
        case 'error':
          throw error;
        case 'success':
          return result;
      }
    },
  };
}

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

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

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

Loading UI Patterns#

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

// Progressive loading
function Article() {
  return (
    <article>
      {/* Title loads first */}
      <Suspense fallback={<TitleSkeleton />}>
        <ArticleTitle />
      </Suspense>

      {/* Then content */}
      <Suspense fallback={<ContentSkeleton />}>
        <ArticleContent />
      </Suspense>

      {/* Comments load last */}
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments />
      </Suspense>
    </article>
  );
}

// Inline loading indicator
function LoadingOverlay({ children, isLoading }) {
  return (
    <div className="relative">
      {children}
      {isLoading && (
        <div className="absolute inset-0 bg-white/50 flex items-center justify-center">
          <Spinner />
        </div>
      )}
    </div>
  );
}

Testing Suspense#

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

test('shows loading then content', async () => {
  render(
    <Suspense fallback={<div>Loading...</div>}>
      <AsyncComponent />
    </Suspense>
  );

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

  // Eventually shows content
  await waitFor(() => {
    expect(screen.getByText('Content')).toBeInTheDocument();
  });
});

// Mock suspense resource
jest.mock('./api', () => ({
  fetchUser: jest.fn(() =>
    Promise.resolve({ name: 'John' })
  ),
}));

Best Practices#

Boundaries:
✓ Place boundaries around independent sections
✓ Use nested boundaries for granular loading
✓ Combine with error boundaries
✓ Keep fallbacks visually similar

Performance:
✓ Start fetching before render when possible
✓ Use transitions for navigation
✓ Defer non-critical updates
✓ Stream SSR content

UX:
✓ Use skeleton screens over spinners
✓ Show partial content early
✓ Maintain layout stability
✓ Provide retry mechanisms

Suspense boundaries declaratively handle async loading states. Place them strategically for granular loading, combine with error boundaries for resilience, and use transitions for smooth navigation. In Next.js, leverage streaming SSR for optimal performance.