React Suspense Patterns and Best Practices

React Suspense enables declarative loading states. Here's how to use it effectively for data fetching and code splitting.

Basic Suspense#

import { Suspense, lazy } from 'react';

// Code splitting with lazy
const HeavyComponent = lazy(() => import('./HeavyComponent'));

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <HeavyComponent />
    </Suspense>
  );
}

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

function App() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/analytics" element={<Analytics />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

Data Fetching with Suspense#

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

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

  // No loading check needed - Suspense handles it
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

function UserPage({ userId }: { userId: string }) {
  return (
    <Suspense fallback={<ProfileSkeleton />}>
      <UserProfile userId={userId} />
    </Suspense>
  );
}

// Multiple suspending components
function Dashboard() {
  return (
    <div className="dashboard">
      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>

      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />
      </Suspense>

      <Suspense fallback={<TableSkeleton />}>
        <RecentOrders />
      </Suspense>
    </div>
  );
}

Nested Suspense Boundaries#

// Granular loading states
function ProductPage({ productId }: { productId: string }) {
  return (
    <div className="product-page">
      {/* Critical content loads first */}
      <Suspense fallback={<ProductHeaderSkeleton />}>
        <ProductHeader productId={productId} />

        {/* Secondary content can load independently */}
        <div className="product-details">
          <Suspense fallback={<DescriptionSkeleton />}>
            <ProductDescription productId={productId} />
          </Suspense>

          <Suspense fallback={<ReviewsSkeleton />}>
            <ProductReviews productId={productId} />
          </Suspense>
        </div>
      </Suspense>

      {/* Recommendations load last */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <RelatedProducts productId={productId} />
      </Suspense>
    </div>
  );
}

// Avoid nested loading waterfalls
// Bad: Each component waits for parent to load
function BadPattern() {
  return (
    <Suspense fallback={<Loading />}>
      <Parent>
        <Suspense fallback={<Loading />}>
          <Child /> {/* Waits for Parent to load */}
        </Suspense>
      </Parent>
    </Suspense>
  );
}

// Good: Parallel loading with SuspenseList
import { SuspenseList } from 'react';

function GoodPattern() {
  return (
    <SuspenseList revealOrder="forwards">
      <Suspense fallback={<HeaderSkeleton />}>
        <Header />
      </Suspense>
      <Suspense fallback={<ContentSkeleton />}>
        <Content />
      </Suspense>
      <Suspense fallback={<FooterSkeleton />}>
        <Footer />
      </Suspense>
    </SuspenseList>
  );
}

Error Boundaries with Suspense#

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

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

function DataSection() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <Suspense fallback={<LoadingSpinner />}>
        <DataComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

// Retry on error
function RetryableSection({ queryKey }) {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onReset={() => {
        queryClient.invalidateQueries({ queryKey });
      }}
      resetKeys={[queryKey]}
    >
      <Suspense fallback={<Skeleton />}>
        <DataComponent queryKey={queryKey} />
      </Suspense>
    </ErrorBoundary>
  );
}

Streaming SSR with Suspense#

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

async function SlowComponent() {
  const data = await fetchSlowData(); // Takes 2 seconds
  return <div>{data}</div>;
}

async function FastComponent() {
  const data = await fetchFastData(); // Takes 100ms
  return <div>{data}</div>;
}

export default function Page() {
  return (
    <div>
      {/* Fast content streams immediately */}
      <Suspense fallback={<FastSkeleton />}>
        <FastComponent />
      </Suspense>

      {/* Slow content streams when ready */}
      <Suspense fallback={<SlowSkeleton />}>
        <SlowComponent />
      </Suspense>
    </div>
  );
}

// The HTML streams progressively:
// 1. Shell with fallbacks sent immediately
// 2. FastComponent content injected (~100ms)
// 3. SlowComponent content injected (~2s)

Transitions with Suspense#

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

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

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

  return (
    <div>
      <TabButtons
        selectedTab={tab}
        onSelect={selectTab}
        isPending={isPending}
      />

      <div className={isPending ? 'pending' : ''}>
        <Suspense fallback={<TabSkeleton />}>
          {tab === 'home' && <HomeTab />}
          {tab === 'posts' && <PostsTab />}
          {tab === 'contact' && <ContactTab />}
        </Suspense>
      </div>
    </div>
  );
}

// Keep showing old content while loading new
// isPending lets you show loading indicator without hiding content

Preloading Data#

// Preload on hover/focus
const preloadUser = (userId: string) => {
  queryClient.prefetchQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
};

function UserLink({ userId, children }) {
  return (
    <Link
      to={`/users/${userId}`}
      onMouseEnter={() => preloadUser(userId)}
      onFocus={() => preloadUser(userId)}
    >
      {children}
    </Link>
  );
}

// Preload component code
const UserProfile = lazy(() => import('./UserProfile'));

function preloadUserProfile() {
  import('./UserProfile');
}

function UserLink({ userId }) {
  return (
    <Link
      to={`/users/${userId}`}
      onMouseEnter={() => {
        preloadUserProfile();
        preloadUser(userId);
      }}
    >
      View Profile
    </Link>
  );
}

Custom Suspense-Enabled Hook#

// Create a resource for Suspense
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;
    },
    (err) => {
      status = 'error';
      error = err;
    }
  );

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

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

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

Best Practices#

Boundaries:
✓ Place boundaries at meaningful UI sections
✓ Use granular boundaries for independent content
✓ Combine with ErrorBoundary
✓ Consider user experience flow

Performance:
✓ Preload on user intent
✓ Use streaming SSR
✓ Avoid loading waterfalls
✓ Show meaningful skeletons

Patterns:
✓ Use transitions for tab switching
✓ Keep old content visible during loads
✓ Parallel data fetching
✓ Progressive enhancement

React Suspense simplifies loading state management. Place boundaries strategically for optimal UX, combine with error boundaries for resilience, and use transitions to keep the UI responsive. With streaming SSR, you can deliver fast initial loads while progressively enhancing the page.