Suspense & Error Boundaries

Declarative loading. Boundary placement strategy.

<Suspense>used to be exotic. In React 19, it's the standard way to handle anything that takes time: data fetches, lazy-loaded components, images, async values. You wrap a region of your UI in Suspense, give it a fallback, and React shows the fallback while anything inside is still loading.

The basic shape

tsx

import { Suspense } from "react";

<Suspense fallback={<Spinner />}>
  <UserProfile userId={id} />
</Suspense>

While UserProfile (or anything it renders) is suspending, React shows <Spinner />. When everything inside finishes, React swaps it out for the real content. No isLoading state in your component. The component just describes what to render once data exists.

Where to place boundaries

The biggest skill with Suspense is choosing where to put the boundaries. Too few and a single slow fetch hides your whole page. Too many and the UI flickers with spinners everywhere.

Useful guidelines:

One boundary at the route level for the main content.
Inner boundaries around independent sections that can load in parallel (sidebar, recommendations, comments).
Avoid micro-boundaries around every little widget. The flicker tax is real.
Keep the structure of fallback content similar to the real content (use skeletons) to prevent layout shift.

tsx

<Layout>
  <Header />
  <Suspense fallback={<MainSkeleton />}>
    <Main />
    <Suspense fallback={<CommentsSkeleton />}>
      <Comments />
    </Suspense>
  </Suspense>
  <Footer />
</Layout>

The outer boundary covers the main content. The inner boundary lets comments load independently. The footer renders immediately.

Suspense handles loading. ErrorBoundary handles errors.

Suspense only knows about pending. If your fetch fails, the promise rejects, and you need an ErrorBoundaryto catch it. React still doesn't ship one. The community standard is react-error-boundary:

tsx

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

<ErrorBoundary fallback={<p>Couldn&apos;t load comments</p>}>
  <Suspense fallback={<CommentsSkeleton />}>
    <Comments />
  </Suspense>
</ErrorBoundary>

Wrap a region with both: ErrorBoundary on the outside, Suspenseon the inside. If data fails, you see the error fallback. If it's still loading, you see the suspense fallback. Predictable, composable, no isLoading and isError booleans cluttering your components.

ErrorBoundary doesn't catch every error

It catches errors thrown during render and in lifecycle methods. It does NOT catch async errors in event handlers, timers, or anywhere outside React's call stack. For those, use try/catch in the handler.

Document metadata hoists itself

React 19 added something quietly useful: you can put <title>, <meta>, and <link> tags inside any component, and React hoists them to <head> automatically.

tsx

function BlogPost({ post }) {
  return (
    <article>
      <title>{post.title} – My Blog</title>
      <meta name="description" content={post.excerpt} />
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}

That <title> ends up in the document head. No Helmet, no Next-only API, just JSX. Multiple components writing to the same tag use last-write-wins.

Asset preloading

React 19 also exposed a small set of preloading APIs from react-dom:

tsx

import { preload, preconnect, prefetchDNS } from "react-dom";

function App() {
  preload("/fonts/inter.woff2", { as: "font", crossOrigin: "anonymous" });
  preconnect("https://cdn.example.com");
  prefetchDNS("https://api.example.com");
  // ...
}

These add the equivalent <link rel="preload"> tags to <head>. The browser starts fetching the asset in parallel with React rendering. Critical for fonts, hero images, and CDN connections.

Try it: nested suspense with a fake async tree

Two cards. Each loads independently. The outer suspense holds the page until both have started rendering. Watch them stream in.

import { Suspense, use, useState } from "react";

// Cache promises so they aren&apos;t recreated on every render
const cache = new Map();
function fetchData(label, ms, value) {
  if (!cache.has(label)) {
    cache.set(label, new Promise((r) => setTimeout(() => r(value), ms)));
  }
  return cache.get(label);
}

function Card({ label, promise }) {
  const value = use(promise);
  return (
    <div style={{
      padding: 16, marginBottom: 12, borderRadius: 8,
      background: "#f3f4f6", fontFamily: "system-ui",
    }}>
      <strong>{label}</strong>: {value}
    </div>
  );
}

function Skeleton({ label }) {
  return (
    <div style={{
      padding: 16, marginBottom: 12, borderRadius: 8,
      background: "#e5e7eb", color: "#9ca3af", fontFamily: "system-ui",
    }}>
      Loading {label}...
    </div>
  );
}

export default function App() {
  const [version, setVersion] = useState(0);

  function reset() {
    cache.clear();
    setVersion(version + 1);
  }

  const fastPromise = fetchData("fast-" + version, 600, "ready in 600ms");
  const slowPromise = fetchData("slow-" + version, 1800, "ready in 1.8s");

  return (
    <div style={{ padding: 24, fontFamily: "system-ui" }}>
      <h3>Suspense streaming</h3>
      <button onClick={reset}>Reload</button>

      <div style={{ marginTop: 16 }}>
        <Suspense fallback={<Skeleton label="fast card" />}>
          <Card label="Fast card" promise={fastPromise} />
        </Suspense>

        <Suspense fallback={<Skeleton label="slow card" />}>
          <Card label="Slow card" promise={slowPromise} />
        </Suspense>
      </div>
    </div>
  );
}

Open Sandbox

Quiz

Quiz1 / 3

What does <Suspense fallback={x}> show its fallback for?

Recap

<Suspense fallback> shows a placeholder while descendants suspend. Use for loading states, lazy components, async data.
Choose boundary placement carefully. One per logical region, not one per widget.
Suspense handles pending. ErrorBoundary handles errors. Wrap with both for resilience.
Place <title>, <meta>, <link> inline; React 19 hoists them to <head>.
Use preload, preconnect, and prefetchDNS from react-dom for critical assets.