The team’s React app has 300 components. About 200 of them have the same scaffolding:

const { data, isLoading, error } = useUserQuery(userId);
if (isLoading) return <Spinner />;
if (error) return <ErrorBox error={error} />;
return <UserCard user={data} />;

Three branches in every component. The error UI is reimplemented dozens of times. Loading states cascade: first the page, then each section, then each card. The cumulative complexity is real. Suspense is the React feature that collapses those three branches into one, and lets you handle loading and error states higher up the tree. This post is the working pattern with React Query, SWR, and the streaming SSR story.

The mental model

Suspense lets components throw a promise instead of returning UI when their data is not ready. A <Suspense fallback={...}> boundary higher up the tree catches the thrown promise and renders the fallback until the promise resolves. Then it re-renders the children.

<Suspense fallback={<Spinner />}>
  <UserCard userId="42" />
</Suspense>

UserCard doesn’t have to handle loading. It writes its render code as if the data is always there:

function UserCard({ userId }: { userId: string }) {
  const user = useUser(userId); // throws a promise if not ready
  return <div>{user.name}</div>;
}

Errors are similarly handled by an <ErrorBoundary> higher up. The leaf component is just rendering, no branches.

React Query with Suspense

Most data libraries support Suspense via a flag:

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

function UserCard({ userId }: { userId: string }) {
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
  });

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

// Higher in the tree:
<ErrorBoundary fallback={<ErrorBox />}>
  <Suspense fallback={<Spinner />}>
    <UserCard userId="42" />
  </Suspense>
</ErrorBoundary>

useSuspenseQuery always returns data: never null, never undefined, no isLoading flag. If data isn’t ready, it throws a promise; Suspense catches it.

SWR has the same shape with useSWRSuspense.

Where to put the boundaries

A common mistake: one <Suspense> at the top of the page that catches everything. Every section waits for every other section before anything renders. The page is blank for 4 seconds while five queries resolve.

The right pattern: place boundaries to parallelize the loading. Each section has its own boundary; sections render as their data arrives.

function ProductPage() {
  return (
    <>
      <Suspense fallback={<HeaderSkeleton />}>
        <ProductHeader />
      </Suspense>

      <Suspense fallback={<ImagesSkeleton />}>
        <ProductImages />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews />
      </Suspense>
    </>
  );
}

Header, images, and reviews load in parallel. Each appears as its query resolves. Skeletons show meaningful structure during loading instead of one giant spinner.

Skeletons over spinners

A small but real UX win: replace generic spinners with skeletons that match the shape of the eventual content. The user sees layout immediately, even before data:

function HeaderSkeleton() {
  return (
    <div className="animate-pulse">
      <div className="h-8 bg-gray-200 w-48 mb-2" />
      <div className="h-4 bg-gray-200 w-32" />
    </div>
  );
}

The page doesn’t shift when data arrives. Same layout, content fills in. Cumulative Layout Shift drops to zero.

Error boundaries

A React Error Boundary catches errors during render. Suspense throws promises; if the promise rejects, the error bubbles up to the nearest Error Boundary.

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

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div>
      <p>Something went wrong: {error.message}</p>
      <button onClick={resetErrorBoundary}>Retry</button>
    </div>
  )}
>
  <Suspense fallback={<Spinner />}>
    <UserCard userId="42" />
  </Suspense>
</ErrorBoundary>

Place error boundaries where you want errors to be caught, typically wrapping each major section. A failed reviews query shouldn’t break the whole page.

The waterfall trap

Suspense makes loading states look easy and can mask a serious performance problem: cascading sequential queries.

function UserPage({ userId }) {
  const user = useUser(userId);              // query 1
  return <UserOrders userId={user.id} />;     // depends on query 1
}

function UserOrders({ userId }) {
  const orders = useOrders(userId);           // query 2, starts only after query 1
  return <div>{...}</div>;
}

Total time: query 1 latency + query 2 latency. Two sequential round-trips for what could be one.

The fix: fetch in parallel as high in the tree as possible, and pass data down. Or use a backend that returns related data in one call (BFF pattern, GraphQL).

For React Query, you can also kick off both queries in parallel:

function UserPage({ userId }) {
  // Both queries start immediately.
  const user   = useSuspenseQuery({ queryKey: ['user', userId], ... });
  const orders = useSuspenseQuery({ queryKey: ['orders', userId], ... });

  return <div>{user.data.name} - {orders.data.length} orders</div>;
}

This component suspends until both queries resolve. Total time = max of the two latencies.

Streaming SSR with Suspense

In Next.js 14 (App Router) and similar streaming-capable frameworks, Suspense translates to streamed HTML:

// app/page.tsx - Server Component
export default function Page() {
  return (
    <>
      <FastHeader />
      <Suspense fallback={<Skeleton />}>
        <SlowReviews />   {/* Server Component, awaits async data */}
      </Suspense>
    </>
  );
}

The browser receives the FastHeader HTML immediately. The slow Reviews HTML streams in when its data is ready. Time-to-first-byte stays fast even when one section is slow.

This is the streaming SSR story React has been promising for years, now real, in 2024.

Common patterns

Tabbed UI with deferred loading.

<Tabs>
  <Tab name="Overview">
    <Suspense fallback={<Skeleton />}>
      <Overview />
    </Suspense>
  </Tab>
  <Tab name="Activity">
    <Suspense fallback={<Skeleton />}>
      <Activity />     {/* loaded only when tab is opened */}
    </Suspense>
  </Tab>
</Tabs>

The Activity query only fires when its tab is rendered.

Pagination with smooth transitions.

useTransition plus Suspense lets the previous page stay visible during the transition to the next:

const [isPending, startTransition] = useTransition();
const [page, setPage] = useState(1);

const onNext = () => startTransition(() => setPage(page + 1));

return (
  <>
    <button onClick={onNext} disabled={isPending}>Next</button>
    <Suspense fallback={<Skeleton />}>
      <PageContents page={page} />
    </Suspense>
  </>
);

startTransition marks the state update as non-urgent, so Suspense doesn’t show the fallback for it. The user sees the old page until the new one is ready.

Caveats and gotchas

Server Components vs Client Components. In Next.js App Router, server components can directly await data, no Suspense library needed in the leaves. Suspense boundaries still control streaming. Client components use React Query / SWR.

Hydration mismatches. SSR + Suspense + Client Components requires careful boundary placement. Mismatches show up as runtime warnings.

Tooling support. Older state management libraries don’t integrate with Suspense. React Query 5+, SWR 2+, Apollo Client (with Suspense flag) work. Anything older may not.

Browser back/forward. Suspense fallbacks may flash on navigation if the cache is empty. React Query persists across renders; configure staleTime appropriately.

When NOT to use Suspense

A few cases:

• Forms with controlled inputs. The pattern doesn’t fit well; inputs need to render immediately, not “suspend until data.”
• Optimistic updates. Suspense is about waiting; optimistic updates are about showing the future state immediately. Different concerns.
• Tightly coupled to a non-Suspense library. Migrating piecemeal is doable but messy.

For data-driven views (lists, dashboards, content pages), Suspense is the right default. For interactive forms, conventional state and isLoading flags still work better.

The takeaway

Suspense replaces the if-loading-if-error-if-data ceremony with declarative boundaries. Wrap sections, use Suspense-enabled queries, render skeletons that match the shape of content. Place boundaries to parallelize, not serialize. Watch for waterfall traps. Pair with streaming SSR if you’re using Next.js or similar.

The components get shorter, the loading states more consistent, and the page feels faster because users see something immediately. The migration is incremental, a section at a time. Start with one card, see the difference, propagate.

A note from Yojji

The kind of frontend architecture choices that turn a noisy data-fetching layer into a clean Suspense-driven tree (boundaries placed for parallelism, skeletons that match content, streaming SSR) is the kind of detail Yojji’s frontend teams put into the products they ship for clients.

Yojji is an international custom software development company founded in 2016, with teams in Europe, the US, and the UK. They specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms, and full-cycle frontend engineering, including the React patterns that decide whether a UI feels responsive or laggy.